使用说明

Claude Code MCP并行编排

将顺序MCP操作转换为并行执行

这有什么作用

此工具包支持 并行执行 克劳德内部MCP-CLI运营代码，减少挂钟时间 高达18倍 用于批量操作。

# Without this toolkit (sequential): ~76 seconds for 20 calls
mcp-cli call server/tool1 '{}'   # 3.8s
mcp-cli call server/tool2 '{}'   # 3.8s
# ... 18 more calls

# With this toolkit (parallel): ~4.9 seconds for 20 calls
mcp-cli call server/tool1 '{}' > /tmp/r1.json &
mcp-cli call server/tool2 '{}' > /tmp/r2.json &
# ... 18 more calls
wait

三层

此工具包弥补了Claude Code中的架构差距。这是完整图片：

图层	名称	状态	功能
L1	子代理并行性	✅ 工作	多个代理并行
L2	工具调用并行性	❌ 未实施	每回合使用多个工具
L3	MCP-CLI并行性	✅ Works	Bash中的后台作业

L2为什么重要： Claude API支持并行工具调用，但Claude代码没有实现这一点。我们通过对113个会话的分析发现了这一点显示了在单个代理回合内并行执行的0/3441个工具调用。

我们可以控制的： L1和L3。该工具包侧重于L3（主要加速），L1用于吞吐量扩展。

业绩：诚实数字

L3：MCP-CLI并行性（主要值）

这是核心技术。真正的加速——同样的工作，更少的时间：

并行呼叫	顺序时间	并行时间	加速
2	~7.6秒	~3.8秒	2.0倍
5秒至19秒	5.0倍
10秒	~38秒	~3.9秒	9.7倍
20秒	~76秒	~4.9秒	15.5x
50（批量）	~190秒	~10.5秒	18.1x

关键见解： 20个MCP呼叫需要76秒，现在需要4.9秒。

L1：子代理并行性（吞吐量缩放）

Claude Code的任务工具允许在一条消息中生成多个子代理。 这是吞吐量扩展，而不是加速。

配置	功能	挂钟时间
1名特工，17次L3行动	17次行动完成	~3.2秒
3个代理，每个代理17个L3操作	51个操作完成	~3.5秒
6个代理，每个L3操作17个	102个操作完成	~4.0秒

重要区别：

L1不会使L3更快
L1允许同时进行更多操作
相同的挂钟时间，处理的总操作数增加6倍

L2：我们正在弥补的差距

Claude Code没有第2层（转弯内的并行工具调用）实施。如果这样做，每个子代理都可以同时调用多个工具。我们通过最大化L1和L3来进行补偿。

组合效应：你实际得到的

┌─────────────────────────────────────────────────────────────────────────────────┐
│  HONEST PERFORMANCE CLAIMS                                                      │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  L3 (MCP-CLI Parallelism):                                                      │
│  ─────────────────────────                                                      │
│  • Speedup: 2x-18x depending on batch size                                      │
│  • Same operations, less wall-clock time                                        │
│  • Diminishing returns above ~50 parallel calls                                 │
│                                                                                 │
│  L1 (Subagent Parallelism):                                                     │
│  ─────────────────────────                                                      │
│  • Throughput: ~6x more operations per wall-clock second                        │
│  • Horizontal scaling, not vertical speedup                                     │
│  • Adds startup overhead (~1-2s per agent)                                      │
│                                                                                 │
│  L1 + L3 Combined:                                                              │
│  ─────────────────                                                              │
│  • Process 100+ operations in ~5s                                               │
│  • Sequential baseline for same work: ~400s                                     │
│  • Effective speedup for large workloads: ~80x                                  │
│  • But most of this comes from L3 alone                                         │
│                                                                                 │
│  WHAT L1 ACTUALLY ADDS TO L3:                                                   │
│  ─────────────────────────────                                                  │
│  • For fixed operations: marginal improvement (~1.2-1.5x)                       │
│  • For variable operations: ~6x more throughput at similar latency              │
│  • Primary value: domain separation (calendar agent, email agent, git agent)    │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

建筑深潜

对于那些想要了解上述三层模型更多细节的人：

┌─────────────────────────────────────────────────────────────────────────────────┐
│                        THREE-LAYER PARALLELISM ARCHITECTURE                      │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  L1: SUBAGENT PARALLELISM (✅ Works)                                            │
│  ═══════════════════════════════════                                            │
│  Main session spawns multiple Task tools in ONE message                         │
│  Effect: Horizontal scaling (more agents working simultaneously)                │
│  NOT a speedup for fixed work — it's throughput scaling                         │
│                                                                                 │
│  L2: TOOL CALL PARALLELISM (❌ Not implemented)                                 │
│  ═════════════════════════════════════════════                                  │
│  The Claude API supports this. Claude Code does not use it.                     │
│  We cannot control this layer — hence this toolkit's existence.                 │
│                                                                                 │
│  L3: MCP-CLI PARALLELISM (✅ Works)                                             │
│  ═════════════════════════════════                                              │
│  Background jobs within Bash: `mcp-cli ... &`                                   │
│  Effect: Genuine speedup (2x-18x for same operations)                           │
│  THIS IS THE PRIMARY VALUE of this toolkit                                      │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

比较：加速与吞吐量

层	它提供什么	加速（相同的工作）	吞吐量（更多的工作）
L1	平行子代理	~1x（边缘）	~6倍
L2	并行工具调用	N/A（间隙）	N/A
L3	并行MCP-CLI	2x-18x	~1x

快速开始

安装（用户级别，所有项目）：

curl -fsSL https://raw.githubusercontent.com/AIntelligentTech/claude-code-mcp-cli-parallel-godmode/main/get.sh | bash

安装（仅限当前项目）：

curl -fsSL https://raw.githubusercontent.com/AIntelligentTech/claude-code-mcp-cli-parallel-godmode/main/get.sh | bash -s -- --project .

然后重新启动Claude Code。

Manual install

git clone --depth 1 https://github.com/AIntelligentTech/claude-code-mcp-cli-parallel-godmode.git /tmp/mcp-parallel
/tmp/mcp-parallel/install.sh --user
rm -rf /tmp/mcp-parallel

核心模式：L3并行

主要技术。使用后台作业 & 和 wait:

# Execute operations in parallel
mcp-cli call google-workspace/get_events '{}' > /tmp/events.json &
mcp-cli call google-workspace/list_tasks '{}' > /tmp/tasks.json &
mcp-cli call google-workspace/search_gmail_messages '{}' > /tmp/email.json &
wait

# Process results
cat /tmp/events.json /tmp/tasks.json /tmp/email.json

所需元素

要素	目的
`&`	在后台运行命令
`> /tmp/file.json`	捕获输出（后台作业需要此功能）
`wait`	阻止，直到所有后台作业完成

大型作业的波浪配料

对于50+个操作，批处理成波浪以避免资源耗尽：

# Process 100 operations in waves of 25
for wave in 1 2 3 4; do
  start=$((($wave - 1) * 25 + 1))
  end=$(($wave * 25))

  for i in $(seq $start $end); do
    mcp-cli call server/tool "{\"id\":$i}" > /tmp/r$i.json &
  done
  wait  # Complete wave before starting next
done

高级模式：L1+L3（吞吐量扩展）

当您需要跨不同域处理许多操作时，请使用子代理为了 水平扩展:

# Main session sends ONE message with multiple Task tools
# All agents execute in parallel (L1), each using parallel MCP (L3)

Task:
  subagent_type: general-purpose
  description: "Calendar scanner"
  prompt: |
    Fetch calendar events using parallel MCP-CLI.

    mcp-cli call google-workspace/get_events '{"calendar_id":"cal1"}' > /tmp/cal1.json &
    mcp-cli call google-workspace/get_events '{"calendar_id":"cal2"}' > /tmp/cal2.json &
    wait

    Target output: 400-600 tokens (structured YAML).

Task:
  subagent_type: general-purpose
  description: "Email scanner"
  prompt: |
    Fetch recent emails using parallel MCP-CLI.

    mcp-cli call google-workspace/search_gmail_messages '{"query":"is:unread"}' > /tmp/unread.json &
    mcp-cli call google-workspace/search_gmail_messages '{"query":"in:inbox"}' > /tmp/inbox.json &
    wait

    Target output: 400-600 tokens.

Task:
  subagent_type: general-purpose
  description: "Git analyzer"
  prompt: |
    Analyze git repositories with parallel commands.

    for repo in /path/to/repos/*; do
      git -C "$repo" log --oneline -10 &
    done
    wait

    Target output: 400-800 tokens.

结果：

3个代理并行运行（L1）
每个代理并行运行2-10个操作（L3）
总计：~4s内完成约20次操作
连续基线：~80s

注：这是吞吐量扩展。仅L3的20次操作将大约需要4秒。L1在这里的值是域分离和更清晰的代码，而不是额外的加速。

文件系统通信模式

对于大型数据集，让子代理写入文件，然后有选择地读取：

# Subagent writes data to temp files
mcp-cli call google-workspace/get_events '{}' > /tmp/data/events.json &
mcp-cli call google-workspace/list_tasks '{}' > /tmp/data/tasks.json &
wait

# Create manifest summarizing what was collected
cat > /tmp/data/manifest.json << 'EOF'
{
  "files": ["events.json", "tasks.json"],
  "summary": {"events": 15, "tasks": 8}
}
EOF

# Main session reads manifest first, then selectively loads
Read: /tmp/data/manifest.json
Read: /tmp/data/events.json  # Only if needed based on manifest

好处： 子代理可以处理10万多个代币；主会话只加载它所加载的内容需要。

已知问题

问题1：子代理模型选择错误

设置 model: haiku 任务工具中没有可靠地使用指定的模型。

解决方法： 在提示中使用令牌预算约束：

Task:
  prompt: |
    ...
    IMPORTANT: Target output 400-600 tokens maximum.
    Return structured YAML, not verbose prose.

问题2：第2层未实现

Claude API支持一个回合内的并行工具调用。Claude Code不使用这种能力。我们用L1和L3进行补偿。

问题3：会话上下文丢失

不要使用 bash -c 使用mcp-cli时，它会丢失会话上下文：

# WRONG - loses MCP session context
bash -c 'mcp-cli call server/tool "{}"'

# CORRECT - preserves session
mcp-cli call server/tool '{}' > /tmp/result.json &
wait

反模式

顺序MCP呼叫

# WRONG: 3x time
mcp-cli call server/tool1 '{}'
mcp-cli call server/tool2 '{}'
mcp-cli call server/tool3 '{}'

# RIGHT: 1x time (parallel)
mcp-cli call server/tool1 '{}' > /tmp/r1.json &
mcp-cli call server/tool2 '{}' > /tmp/r2.json &
mcp-cli call server/tool3 '{}' > /tmp/r3.json &
wait

缺少输出重定向

# WRONG: output lost
mcp-cli call server/tool '{}' &
wait
# Where did the output go?

# RIGHT: output captured
mcp-cli call server/tool '{}' > /tmp/result.json &
wait
cat /tmp/result.json

忘记等待

# WRONG: results incomplete
mcp-cli call server/tool1 '{}' > /tmp/r1.json &
mcp-cli call server/tool2 '{}' > /tmp/r2.json &
cat /tmp/r1.json  # File may not exist or be incomplete!

# RIGHT: wait for completion
mcp-cli call server/tool1 '{}' > /tmp/r1.json &
mcp-cli call server/tool2 '{}' > /tmp/r2.json &
wait
cat /tmp/r1.json /tmp/r2.json

声称L1提供了加速

# MISLEADING: "6x faster with subagents"
# L1 provides throughput scaling, not speedup for fixed work

# ACCURATE: "6x more operations in same wall-clock time"

需求

依赖关系	安装
jq	`brew install jq` （macOS）/ `apt install jq` （Ubuntu）
bash 4.0+	预装在macOS/Linux上
克劳德代码2.1.12+	claude.ai/claude-code

环境变量：

export ENABLE_EXPERIMENTAL_MCP_CLI=true

文档

文档	内容
docs/三层架构.md	技术架构深度挖掘
docs/real-world-patterns.md	生产测试图案
示例/README.md	代码示例

贡献

欢迎捐款。请确保索赔有可重复的支持基准。

许可证

MIT许可证。看许可证.

报告Bug · 请求功能

由...创建 A智能技术 ·一月 2026