Skip to main content
Glama
LianXia233

mcp-agent-hub

by LianXia233
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

mcp-agent-hub

让多个 Agent 客户端（Claude Code、Cursor、MiMo、Aider 等，可 2 个以上）在本机或局域网互通协作的 MCP 服务。

协作模型：手动设主 + 其余全是子代理

  • 手动指定一个主理人（master）：在某个客户端启动时 --role-type master，或调用 set_master

  • 其余全部是子代理（subagent）：数量不限；入网时自动挂靠到当前主理人

  • 支持本地（多个 stdio 进程共享一个 SQLite）和局域网（Streamable HTTP，多客户端接入同一 Hub）

                ┌─────────────────────┐
                │  主理人 master       │  ← 手动指定（--role-type master / set_master）
                │  拆解 · 派单 · 盯进度 │
                └──────────┬──────────┘
           dispatch_task   │   report / escalate
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
 ┌────────────┐     ┌────────────┐     ┌────────────┐
 │ 子代理 A    │     │ 子代理 B    │     │ 子代理 C    │  ← 可任意多个
 │ coder      │     │ reviewer   │     │ tester     │
 └────────────┘     └────────────┘     └────────────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           ▼
              共享黑板 remember/recall
              任务看板 · 消息收件箱 (SQLite)

Related MCP server: QMCP MultiRoom MCP Server

安装

依赖：Python 3.12+，推荐 uv。

git clone <repo-url> mcp-agent-hub
cd mcp-agent-hub
uv sync
# 或仅运行时
uv pip install -e .

快速开始（Linux 示例）

场景 1：本机多客户端（stdio + 共享 DB）

所有客户端指向同一个 AGENT_HUB_DB 即可互通。主理人手动设在其中一个客户端上。

export AGENT_HUB_DB=/tmp/agent-hub.db

# ① 手动设主：这一端是主理人
mcp-agent-hub stdio --name boss --role-type master --role orchestrator

# ② 其余全是子代理（可开任意多个）
mcp-agent-hub stdio --name coder-1    --role-type subagent --role implementer --capabilities code,test
mcp-agent-hub stdio --name reviewer-1 --role-type subagent --role reviewer    --capabilities review,docs
mcp-agent-hub stdio --name tester-1   --role-type subagent --role tester      --capabilities test

主理人客户端配置（examples/01-master.json）：

{
  "mcpServers": {
    "agent-hub": {
      "command": "mcp-agent-hub",
      "args": ["stdio", "--name", "boss", "--role-type", "master", "--role", "orchestrator"],
      "env": { "AGENT_HUB_DB": "/tmp/agent-hub.db" }
    }
  }
}

子代理客户端配置（换 --name / --role 即可再开 N 个，见 examples/02-04）：

{
  "mcpServers": {
    "agent-hub": {
      "command": "mcp-agent-hub",
      "args": ["stdio", "--name", "coder-1", "--role-type", "subagent", "--role", "implementer", "--capabilities", "code,test"],
      "env": { "AGENT_HUB_DB": "/tmp/agent-hub.db" }
    }
  }
}

场景 2：局域网 / 跨机器（Streamable HTTP）

一台机器起 Hub，其他机器的 Agent 客户端都连上来：

mcp-agent-hub serve --host 0.0.0.0 --port 8765 --db /var/lib/agent-hub/hub.db
# 或
./scripts/run-serve.sh 0.0.0.0 8765

客户端配置：

{
  "mcpServers": {
    "agent-hub": {
      "url": "http://192.168.1.10:8765/mcp"
    }
  }
}

HTTP 模式下多个客户端共享一个服务进程。各方先 join_hub 登记身份（主理人可 set_master），工具也可带 agent 参数指定身份。

手动设主的两种方式

  1. 启动时指定：mcp-agent-hub stdio --name boss --role-type master

  2. 运行时指定：任意 Agent 调用 set_master(name="boss")（exclusive=true 会把其他人降为子代理，并改挂汇报线）

之后 join_hub(role_type="subagent") 的新 Agent 会自动挂靠到当前主理人。

协作流程（1 主 + N 子）

步骤

主理人

子代理（×N）

1. 设主

--role-type master 或 set_master

join_hub(role_type=subagent) 自动挂靠

2. 派单

dispatch_task(title, assignee=coder-1)

收到 order 消息

3. 领会

—

my_assignments / read_inbox

4. 执行

team_status 看全员负载

report_progress(task_id, 50, note)

5. 同步

broadcast / send_message

send_message / escalate

6. 沉淀

remember / recall

remember / recall

7. 交付

收到 report

complete_task(task_id, result)

多个子代理可同时干活；任务池模式用 claim_task 抢占，避免重复劳动。

MCP 工具一览

分组

工具

说明

身份

whoami / join_hub / list_agents / set_status

登记与在场

设主

set_master

手动指定谁是主理人

主理人

dispatch_task / team_status

派单、盯全员负载

子代理

my_assignments / claim_task / report_progress / complete_task / escalate

领活、认领、汇报、交付、上报

任务

create_task / list_tasks / update_task

看板与改派（支持 parent_id 子任务树）

消息

send_message / broadcast / read_inbox / mark_read

点对点、全员广播、房间

房间

create_room / join_room / list_rooms

频道协作

黑板

remember / recall / forget

跨 Agent 共享记忆（带版本）

诊断

hub_stats / activity_log

总览与事件流

环境变量

变量

默认

说明

AGENT_HUB_DB

./agent-hub.db

SQLite 路径（多客户端务必同一文件）

AGENT_NAME

—

默认 Agent 名（也可用 --name）

AGENT_ROLE_TYPE

subagent

master 或 subagent（主理人请设为 master）

AGENT_ROLE

—

职责描述

AGENT_CAPABILITIES

—

能力标签，逗号分隔

AGENT_REPORTED_TO

—

子代理汇报的主理人名字（不填则自动挂靠）

开发

uv sync
uv run ruff check src tests
uv run ruff format src tests
uv run pyright src
uv run pytest
uv run python tests/e2e_mcp_handshake.py

设计说明

  • 手动设主：--role-type master / set_master / join_hub(role_type=master) 三种入口。

  • 自动挂靠：子代理入网时若未指定 reported_to，自动指向当前主理人。

  • 派单：dispatch_task 建任务并给子代理发 order 消息；可派给任意多个子代理。

  • 回报：report_progress / complete_task 自动给主理人发 report；escalate 标 blocked 并发 escalation。

  • 抢占：claim_task 事务内抢占，失败会提示当前持有者。

  • 存储：SQLite + WAL，多进程/多客户端并发安全。

  • 传输：stdio（本机多客户端共享 DB）；serve（局域网 Streamable HTTP）。

参考与联调示例（Reference）

本仓库 reference/ 目录收录真实联调中沉淀的问题总结与可直接复用的客户端测试脚本，覆盖通讯、派发、执行、响应、深度探针等完整链路：

  • reference/hub-integration-reference.md — 安装与联调问题总结：dispatch_task 的 assignee 注册前置约束、streamable_http 客户端 API 差异、轮询按 task_id 精确匹配、真实客户端行为修正、serve 进程生命周期、stdio 与 serve 为独立 Hub 等。

  • reference/test_comm.py — 双客户端 HTTP 全链路通讯（派单→领活→回报→共享黑板 remember/recall→私信）。

  • reference/test_dispatch.py — 向真实子代理派单并验证 order 派令抵达；结束自动取消清理。

  • reference/test_exec.py — 受控子代理 执行→响应 闭环 + 真实客户端轮询。

  • reference/test_probe.py — 针对真实客户端的派发+响应深度探针（order / 私信 / 广播三种触发）。

  • reference/test_dowork.py — 「响应 + 实际做任务」终验：受控子代理真实计算并回报真实产出；真实客户端执行并回报。

运行前置

pip install "mcp[cli]"      # 提供 mcp.client.streamable_http
python reference/test_comm.py

提示：脚本默认 URL="http://127.0.0.1:8765/mcp"，需先 mcp-agent-hub serve --host 0.0.0.0 --port 8765 起 Hub。dispatch_task 要求 assignee 已 join_hub 注册（详见 reference/hub-integration-reference.md 第一节）。

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • QMCP MultiRoom MCP Server

    kduagent
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables agents and users to collaborate across rooms with shared tasks, messages, blackboards, documents, search, plugin registration, visualizations, OAuth helpers, and quantum-circuit simulation plus collaborative model training. It runs over STDIO by default, with optional HTTP/SSE deployment for container-based hosting.
    -

  • Work Commander

    waksana
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables agents to register tasks, dispatch work under explicit caller/owner credentials, amend goals, report and deliver results, read outstanding records, and manage task dependencies through a structured SQLite-backed coordination service. Ships paired collaboration skills for discussing parties and executing owners, keeping a single canonical task identity so work boards reflect the latest reports without monitoring or auto-dispatch.
    -

  • synco-mcp

    ijustseen
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables multiple AI coding agents to coordinate on a shared software project by registering, claiming tasks, declaring file intents, publishing structured change reports, and handing off context, with a local dashboard showing state in near real time.
    -