claude-orchestrator
This MCP server lets Cursor's main agent orchestrate Claude CLI subagents to run development tasks, monitor them, and resume sessions without blocking.
dispatch_task: Launch a single task to a Claude CLI subagent, with optional sync/async mode, custom system prompt, model, allowed tools, working directory, and max turns.
dispatch_parallel: Fan out multiple independent tasks concurrently to separate Claude CLI subagents.
dispatch_goal (per README): Dispatch a goal-driven task where the subagent keeps working until a measurable completion condition is met.
get_task_status: Query a task's current status and recent log output.
get_task_result: Fetch a task's final result snapshot; optionally wait up to 120 seconds for completion.
list_tasks: List all tasks managed by the server, optionally filtered by status.
send_instruction: Resume a completed or stopped task's session with a new instruction; returns a new task ID.
stop_task: Stop a running task and optionally remove it from the registry.
Tasks run as background
claude -pchild processes; dispatch tools returntask_idimmediately, and monitoring tools are read-only and non-blocking.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@claude-orchestrator delegate implementing user auth endpoints to a Claude subagent and run tests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
claude-orchestrator
让 Cursor 主 Agent 通过 MCP 协议调度 Claude CLI 作为子代理
这是什么?
一个 MCP Server,它在 Cursor IDE 和 Claude CLI 之间架起桥梁。Cursor 的主 Agent 作为规划者和协调者,通过 MCP 工具将实际开发任务派发给 Claude CLI(子代理)执行。
┌──────────────────────────────────┐
│ Cursor 主 Agent │
│ 理解需求 → 拆分任务 → 汇总结果 │
└────────────┬─────────────────────┘
│ MCP Protocol (stdio)
┌────────────▼─────────────────────┐
│ claude-orchestrator MCP Server │
│ 任务注册表 + CLI 封装 + 8个工具 │
└────────────┬─────────────────────┘
│ spawn: claude -p --output-format stream-json
┌────────────▼─────────────────────┐
│ Claude CLI (子代理) │
│ 编写代码 / 运行测试 / 代码审查 │
└──────────────────────────────────┘Related MCP server: native-agent-router
为什么需要它?
Cursor 内置的 subagent 能力有限。Claude CLI(Claude Code)拥有完整的开发工具集:
✅ 完整的文件系统操作
✅ 会话可续接(
--resume,对应send_instruction)✅ 自定义系统提示和模型选择
✅ 结构化结果指标(cost / duration / turns)
✅ 灵活的工具配置
安装
git clone https://github.com/lilyjem/cursor-subagent.git
cd cursor-subagent
npm install前置要求:
Node.js >= 20
Claude CLI 已安装并认证
配置 Cursor
将以下内容添加到 Cursor 的 MCP 配置中(~/.cursor/mcp.json):
{
"mcpServers": {
"claude-orchestrator": {
"command": "npx",
"args": ["tsx", "/path/to/cursor-subagent/src/index.ts"]
}
}
}重启 Cursor 后,MCP Server 会自动启动。
8 个 MCP 工具
工具 | 用途 |
| 派发单个任务,立即返回 |
| 派发目标驱动任务,子代理持续工作到条件达成为止 |
| 并行派发多个任务(每项 |
| 查询任务状态与最近日志(纯读取,不阻塞) |
| 取任务结果快照(含 cost / duration / turns),不等待 |
| 列出全部任务( |
| 向已有会话追加指令,返回新任务的 |
| 停止运行中的任务,可选清理记录 |
没有 mode / wait 参数:派发类工具立即返回 task_id,查询类工具只读快照,全部零阻塞。
使用示例
派发任务(立即返回)
dispatch_task({
prompt: "编写一个 Express REST API 的用户注册端点",
system_prompt: "你是 Node.js 后端开发专家"
})
// → { task_id, pid, status: "running" }
// 注意:派发返回值里【没有】session_id —— init 事件到达后由 get_task_status 取目标驱动任务(dispatch_goal)
派发一个完成条件,让子代理自己干到条件达成为止:
dispatch_goal({
goal: "npm test 退出码为 0,且在输出中贴出测试通过数;不得修改 test/ 与 package.json;or stop after 20 turns"
})写条件的四条要诀:
一个可测量的终态 —— 「
npm test退出码为 0」「git status干净」「无 TS 编译错误」,而不是「代码更好」说明怎么证明 —— 评估器不读文件、不跑命令,只看会话里出现过的证据,所以要让子代理把证据留在输出里
附上约束 —— 「且未修改
test/与package.json」。别写「不修改test/之外的文件」:那等于允许改test/,子代理只要把断言改弱就能「达成」条件加轮次上限 ——
or stop after 20 turns(Claude Code 原生支持的子句)
条件上限 4000 字符,超长会被直接拒绝(不会启动 CLI)。主观目标(「让代码更优雅」)不适用。
跟踪与取结果
get_task_status({ task_id: "...", include_logs: true }) // 进度行,运行中的任务也能看
get_task_result({ task_id: "..." }) // 结果快照,任务还在跑就返回 running并行任务
dispatch_parallel({
tasks: [
{ prompt: "实现用户注册 API", system_prompt: "后端专家" },
{ prompt: "实现用户登录 API", system_prompt: "后端专家" },
{ goal: "认证中间件全部单测通过,且贴出测试输出", system_prompt: "安全专家" }
]
})追加指令
send_instruction({ task_id: "...", message: "把错误处理补上" })
// → 返回的是【新任务】的 task_id;原任务保留自己的结果代码审查
dispatch_task({
prompt: "审查 src/api/ 目录下的所有代码,关注安全性和性能",
system_prompt: "你是资深代码审查专家,关注 OWASP Top 10 安全风险"
})Cursor Rule
项目包含 .cursor/rules/claude-orchestrator.mdc,它会自动教 Cursor 主 Agent:
何时使用子代理 vs 自己做
如何构造有效的 dispatch 调用
何时用
dispatch_goal、怎么写完成条件最佳实践(提供完整上下文、并行独立任务等)
技术架构
src/
├── index.ts # 入口:stdio 传输
├── server.ts # MCP Server:注册 8 个工具
├── types.ts # 共享类型定义
├── constants.ts # 常量(goal 字符上限、日志缓冲上限等)
├── claude-cli/
│ └── cli-adapter.ts # 纯函数:argv 构建 + stream-json 行解析
├── runtime/
│ └── task-runner.ts # 子进程生命周期 + 日志环形缓冲
├── registry/
│ └── task-registry.ts # 内存任务注册表
└── tools/
├── dispatch.ts # dispatch_task / dispatch_goal / dispatch_parallel
├── monitor.ts # get_task_status / list_tasks
├── result.ts # get_task_result
└── control.ts # stop_task / send_instruction测试
npm test # 运行所有测试(95 个用例)
npm run test:watch # 监听模式
npm run smoke # 真实 CLI 端到端冒烟(会调用 Claude CLI 并产生费用)工作原理
只有一条执行通道:MCP Server 自己 spawn 一个 claude -p 子进程,不等待,立即返回 task_id,任务状态此后由子进程退出事件驱动。
派发:
claude -p --output-format stream-json --verbose --dangerously-skip-permissions -- "<prompt>"--终止选项解析:--allowedTools是变长参数,实测会连同后面的 prompt 一起吞掉(claude 2.1.272)stdout 逐行是 JSON,解析成事件;
system/thinking_tokens(实测占输出体积 86.4%)与 thinking 块直接丢弃最后的
result事件给出 result / cost / duration_ms / num_turns / session_id
Goal 任务:把条件包装成
/goal <条件>作为位置参数传入/goal是 Claude Code 的 slash 命令(v2.1.139+),-p下一次调用内跑完整个循环评估器是 session 级 prompt Stop hook,由独立的小模型判定条件是否达成
会话续接:
claude -p --output-format stream-json --verbose --dangerously-skip-permissions --resume <session_id> -- "<message>"send_instruction用它续接会话,产生新任务记录(resumedFrom指回原任务),不用重复说明上下文
停止:kill 子进程(SIGTERM),会话保留,仍可
--resume
注意事项
⚠️ 使用
--dangerously-skip-permissions跳过权限确认,子代理拥有完整文件系统访问权限⚠️ 失去
claude attach/claude agents可见性:子代理不再出现在 Claude Code 的后台会话列表里,人类无法 attach 接管⚠️ Server 退出(含 Cursor 重载)会中断在跑的子代理:任务注册表在内存中,重启后全部丢失
⚠️ 每个子代理任务的成本不可忽略:四组真实任务的实测成本为 $0.0357(goal 任务)/ $0.0405(带
allowed_tools的普通任务)/ $0.0986、$0.13(更早的探针);按 $0.04–0.13 估算,dispatch_parallel扇出 3 个任务约 $0.12–0.40(3 × 上述区间)⚠️
dispatch_goal依赖 Claude Code 的 hooks 系统与 workspace 信任:/goal的评估器是 settings 里的 session 级 prompt Stop hook,disableAllHooks或allowManagedHooksOnly会让它不可用,未信任的目录同理⚠️ 需要有效的 Claude CLI 认证(API Key 或 OAuth)
License
MIT
Available Tools
7 toolsdispatch_parallelB
并行派发多个任务给不同的 Claude CLI 子代理。所有任务以 async 模式执行。
Inputs: tasks (required).
dispatch_taskA
派发任务给 Claude CLI 子代理。sync 模式等待完成返回结果,async 模式后台执行立即返回 task_id。
Inputs: prompt (required), mode, model, max_turns, +3 more.
get_task_resultA
获取已完成任务的最终结果。如果任务仍在运行,返回当前状态。
Inputs: task_id (required), wait.
get_task_statusB
查询指定任务的当前状态和最近日志输出。
Inputs: task_id (required), include_logs.
list_tasksB
列出所有由本 MCP Server 管理的任务。
Inputs: status_filter.
send_instructionA
向已完成或已停止的任务发送后续指令(resume 会话)。对运行中的任务会先停止再续接。
Inputs: message (required), task_id (required), mode.
stop_taskA
停止运行中的任务。cleanup=true 时同时从注册表和 CLI 中移除。
Inputs: task_id (required), cleanup.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
每个工具都有明确且独特的职责:派发任务(单/并行)、查询状态、获取结果、列出任务、发送指令、停止任务,没有重叠或模糊之处,代理可以清晰区分。
所有工具名遵循一致的动词_名词模式(如dispatch_task, get_task_status, stop_task),风格统一,可预测性强。
7个工具数量适中,覆盖了任务编排的核心操作,没有冗余或缺失,每个工具都有明确用途。
覆盖了任务生命周期的主要阶段(创建、查询、结果、停止、续接),但缺少显式的删除/清理任务工具(虽然stop_task有cleanup选项),整体完整度较高。
Maintenance
Related MCP Connectors
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables MCP clients like Claude Code and Codex to delegate coding tasks to Cursor's CLI agent, which implements changes in the workspace and returns clean, structured results for review.3580 npm9MIT
- AlicenseAqualityBmaintenanceEnables orchestrator agents to route coding tasks to native CLI worker agents via MCP, providing tools for agent discovery, task submission, waiting, inspection, and cancellation.53MIT
- AlicenseBqualityBmaintenanceEnables any MCP host to delegate work to multiple coding-agent CLIs such as Codex, Claude Code, and Antigravity as subagents, preserving native sessions and supporting team-based supervision and agent-to-agent messaging.179 npmApache 2.0
- FlicenseNot gradedqualityAmaintenanceEnables a primary AI assistant to delegate tasks in parallel to specialized local CLI-based AI sub-agents, share project context, and synthesize their responses through a single MCP interface.-