agent-ecosystem/mcp-server

@claude-team/mcp-server

Model Context Protocol (MCP) server for managing Claude Agent Teams kanban board and tasks.

Exposes 13 tools so AI agents (Claude, Cursor, or any MCP-compatible client) can create tasks, manage the kanban board, conduct code reviews, and send messages — backed by the same teamctl.js CLI that powers the Claude Agent Teams UI desktop app.

---

Table of Contents

• Overview
• Relationship to Claude Agent Teams UI
• Quick start
• Prerequisites
• Installation
• Configuration
• Tools Reference
• Data Storage
• Development
• Testing
• Troubleshooting
• License

---

Overview

Implements the Model Context Protocol over stdio. All operations are delegated to teamctl.js, which:

• Stores task data as JSON under ~/.claude/tasks/{teamName}/
• Stores team config under ~/.claude/teams/{teamName}/
• Is installed automatically when you run Claude Agent Teams UI at least once

Use cases

Scenario	Description
Cursor / Claude Desktop	Add the server to MCP config so AI assistants can create tasks, assign owners, move cards, and send messages without leaving the chat
Automation scripts	Programmatic interface to the same task board that Claude Code agents use
Multi-agent workflows	Multiple AI agents sharing one task board, coordinating via comments and messages

Architecture

┌─────────────────────┐     stdio      ┌──────────────────────┐     spawn      ┌─────────────────┐
│  MCP Client         │ ◄────────────► │  @claude-team/       │ ◄────────────► │  teamctl.js     │
│  (Cursor, Claude,   │                │  mcp-server          │                │  ~/.claude/     │
│   custom scripts)   │                │  (FastMCP + 13 tools) │                │  tools/         │
└─────────────────────┘                └──────────────────────┘                └─────────────────┘

---

Relationship to Claude Agent Teams UI

Component	Role
Claude Agent Teams UI	Desktop app (Electron). Visualizes sessions, kanban board, code review, team messaging. Installs teamctl.js on first run.
teamctl.js	CLI at ~/.claude/tools/teamctl.js. Reads/writes task JSON, manages kanban, inboxes, reviews. Used by both the app and agents.
@claude-team/mcp-server	MCP server wrapping teamctl.js so Cursor, Claude Desktop, and other MCP clients can call the same operations as tools.

Agents in Claude Code use teamctl.js via Bash. Agents in Cursor or Claude Desktop use this MCP server. Both operate on the same data.

---

Quick start

1. Run Claude Agent Teams UI at least once (installs teamctl.js)
2. Build the MCP server: cd mcp-server && pnpm install && pnpm build
3. Add to Cursor MCP config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "claude-team-tools": {
      "command": "node",
      "args": ["/absolute/path/to/claude_agent_teams_ui/mcp-server/dist/index.js"]
    }
  }
}

4. Restart Cursor. The 13 tools will appear for the AI assistant.

---

Prerequisites

• Node.js 20+
• Claude Agent Teams UI run at least once (installs teamctl.js to ~/.claude/tools/teamctl.js)

If teamctl.js is missing, the server throws at startup:

teamctl.js not found at ~/.claude/tools/teamctl.js.
Make sure Claude Agent Teams UI has been run at least once,
or set the TEAMCTL_PATH environment variable.

---

Installation

From the monorepo (development)

cd mcp-server
pnpm install
pnpm build

As a dependency

pnpm add @claude-team/mcp-server
# or
npm install @claude-team/mcp-server

---

Configuration

Cursor

Add to ~/.cursor/mcp.json or project .cursor/mcp.json:

{
  "mcpServers": {
    "claude-team-tools": {
      "command": "node",
      "args": ["/path/to/claude_agent_teams_ui/mcp-server/dist/index.js"]
    }
  }
}

With global install (pnpm link or npm link):

{
  "mcpServers": {
    "claude-team-tools": {
      "command": "team-mcp-server"
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

{
  "mcpServers": {
    "claude-team-tools": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
    }
  }
}

Environment variables

Variable	Description
TEAMCTL_PATH	Path to teamctl.js if not at ~/.claude/tools/teamctl.js

---

Tools Reference

All tools require a team parameter (team name, folder under ~/.claude/teams/).

Task CRUD

Tool	Description
task_create	Create a task. Optional: owner, description, blocked_by, related, status, notify, from
task_get	Get a task by ID. Returns full JSON (status, owner, comments, dependencies, work intervals, history)
task_list	List all tasks. Returns JSON array (filter internal tasks client-side if needed)
task_set_status	Set status: pending → in_progress → completed → deleted. Records work intervals
task_set_owner	Assign or unassign owner. Use owner="clear" to unassign. Optional: notify, from

Task collaboration

Tool	Description
task_comment	Add a comment. Sends inbox notification to owner (unless commenter is owner). Optional: from
task_link	Link/unlink dependencies. Types: blocked-by, blocks, related. Bidirectional; circular deps rejected
task_briefing	Human-readable briefing for a member: their assigned tasks vs full board
task_attach	Attach a file. Modes: copy, link. MIME auto-detected (PNG, JPEG, GIF, WebP, PDF, ZIP). Max 20 MB

Kanban board

Tool	Description
kanban_move	Move to review or approved, or clear from board. Moving to column sets status to completed
kanban_reviewers	Manage reviewers: list (JSON array), add, remove

Code review

Tool	Description
review_action	approve — mark approved (optional comment, notify_owner). request-changes — remove from kanban, reset to in_progress, notify owner (comment required)

Messaging

Tool	Description
message_send	Send inbox message to a member. Optional: summary, from. Triggers notifications

---

Data Storage

Location	Contents
~/.claude/tasks/{teamName}/	Task JSON files (1.json, 2.json, …)
~/.claude/teams/{teamName}/	Team config, kanban reviewers, inboxes

Task IDs are numeric (highwatermark). Team and member names must be safe path segments (no ., .., /, \, null bytes).

---

Development

Scripts

Command	Description
pnpm build	Build with tsup → dist/index.js
pnpm dev	Run with tsx (no build)
pnpm test	Run Vitest tests
pnpm test:watch	Watch mode
pnpm typecheck	TypeScript check

Project structure

mcp-server/
├── src/
│   ├── index.ts          # FastMCP server, registers all tools
│   ├── teamctl-runner.ts  # Spawns teamctl.js subprocess
│   ├── output-parser.ts   # Parses JSON / "OK ..." from teamctl stdout
│   ├── schemas.ts         # Zod schemas (team, taskId, member, etc.)
│   └── tools/
│       ├── index.ts       # registerAllTools()
│       ├── task-create.ts
│       ├── task-get.ts
│       ├── ...
│       └── message-send.ts
├── test/
│   ├── tools/             # Per-tool tests
│   ├── teamctl-runner.test.ts
│   ├── output-parser.test.ts
│   └── schemas.test.ts
├── package.json
├── tsup.config.ts
└── vitest.config.ts

Adding a new tool

1. Create src/tools/your-tool.ts with register(server, runner)
2. Add to ALL_TOOLS in src/tools/index.ts
3. Add Zod parameters and map to teamctl CLI args
4. Use parseJsonOutput, parseOkOutput, or parseTextOutput from output-parser.ts
5. Add tests in test/tools/your-tool.test.ts

---

Testing

Tests use a mock ITeamctlRunner (no real teamctl.js required):

pnpm test

For integration tests with real teamctl.js, use the main app: test/main/services/team/teamctl.test.ts.

---

Troubleshooting

Issue	Solution
teamctl.js not found	Run Claude Agent Teams UI at least once, or set TEAMCTL_PATH
Invalid team/member name	Names: 1–128 chars, no ., .., /, \, null bytes
MCP client not discovering tools	Check server starts without errors; use absolute path in config; some clients require it
Timeout errors	Default 10s. Increase via TeamctlRunnerOptions.timeoutMs (code change)

---

License

Same as the parent project: AGPL-3.0.