mq9 MCP 使用手册

简介

RobustMQ broker 内置了 mq9 MCP 能力。启动 broker 之后，AI Agent（Claude、Cursor、Cline、Hermes 等支持 MCP 的工具）可以通过 mq9 进行 Agent 之间的异步通信。

启用后，你的 Agent 就能：

创建自己的邮箱接收消息
给其他 Agent 发消息
查找具有特定能力的 Agent
注册自己让别人能发现

本手册讲怎么连接、使用。broker 端零配置——启动就有，不需要改任何配置文件。

前置条件

已经运行的 RobustMQ broker（默认 8080 端口暴露 HTTP 服务）
一个支持 MCP 的 AI 工具（Claude Desktop、Cursor、Cline 等）

如果还没装 RobustMQ，参考 RobustMQ 安装文档。

快速开始

1. 确认 broker 在运行

bash

robustmq-server status

确认 8080 端口可访问：

bash

curl http://localhost:8080/health

2. 配置你的 AI 工具

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

json

{
  "mcpServers": {
    "mq9": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

重启 Claude Desktop。

Cursor

编辑 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（用户级）：

json

{
  "mcpServers": {
    "mq9": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Cline / Continue / 其他支持 HTTP MCP 的工具

参考各工具的 MCP 配置文档，方式相同——url 设为 http://broker-host:8080/mcp。

3. 验证连接

在 Claude Desktop 里输入：

帮我创建一个 mailbox 叫 test.001

如果返回成功，连接就通了。

关于 stdio 模式

RobustMQ 只暴露 HTTP MCP 端点，不支持 stdio。

如果你的 AI 工具只支持 stdio（少见，大多数现代 AI 工具都支持 HTTP），可以用社区工具 mcp-remote 桥接：

json

{
  "mcpServers": {
    "mq9": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8080/mcp"]
    }
  }
}

mcp-remote 是社区维护的通用桥接工具（npm 包），把任何 HTTP MCP server 桥接成 stdio 模式。RobustMQ 不提供桥接命令，不维护 stdio 兼容层。

工具列表

mq9 MCP 提供以下工具供 LLM 调用：

工具名	用途
`mq9_create_mailbox`	创建一个新的 mailbox
`mq9_send_message`	发送消息给指定 mailbox
`mq9_fetch_messages`	从 mailbox 拉取消息
`mq9_ack_message`	确认消息已处理
`mq9_query_mailbox`	查询 mailbox 中的消息（不消费）
`mq9_register_agent`	把自己注册到 mq9 注册中心
`mq9_discover_agents`	查找具有特定能力的 Agent
`mq9_unregister_agent`	注销自己

下面给出每个工具的参数和典型用法。

工具参考

mq9_create_mailbox

创建一个 mailbox。mailbox 名字必须小写，可包含字母、数字和点。

参数：

参数	类型	必填	默认	说明
`name`	string	否	自动生成	mailbox 名字（仅小写字母、数字、点）。省略时 broker 自动生成
`ttl`	integer	否	broker 默认	存活时间（秒）
`desc`	string	否	-	可读描述

示例：

帮我创建一个 mailbox 叫 task.001.callback，过期时间 1 小时

LLM 会调用：

mq9_create_mailbox(name="task.001.callback", ttl=3600)

mq9_send_message

向指定 mailbox 发送消息。

参数：

参数	类型	必填	默认	说明
`mail_address`	string	是	-	目标 mailbox 地址
`payload`	string	是	-	消息内容（任意字符串）
`priority`	string	否	`normal`	`normal` / `urgent` / `critical`

示例：

给 agent.translator.inbox 发一条消息：'请翻译这段：Hello world'

LLM 会调用：

mq9_send_message(
  mail_address="agent.translator.inbox",
  payload="请翻译这段：Hello world"
)

紧急消息：

给 agent.coordinator.inbox 发一条紧急消息：'系统资源不足，请暂停所有任务'

LLM 会调用：

mq9_send_message(
  mail_address="agent.coordinator.inbox",
  payload="系统资源不足，请暂停所有任务",
  priority="urgent"
)

mq9_fetch_messages

从 mailbox 拉取消息。默认行为是续拉（从上次 ack 位置继续）。

参数：

参数	类型	必填	默认	说明
`mail_address`	string	是	-	mailbox 地址
`group_name`	string	是	-	消费组名。建议用 Agent ID，不同 group 各自维护消费位点
`max_messages`	integer	否	100	最多拉取条数
`reset_to`	string	否	-	重置消费位点（见下方）

reset_to 参数取值：

值	行为
不传	从上次 ack 位置续拉
`"earliest"`	重置到最早的消息
`"latest"`	只拉新消息，跳过历史
`"time:<unix秒>"`	从该时间戳之后开始，如 `"time:1746000000"`
`"id:<msg_id>"`	从该消息开始（含），如 `"id:42"`

示例：

看看我的 inbox 有什么新消息

LLM 会调用：

mq9_fetch_messages(mail_address="claude.desktop.inbox", group_name="my-agent")

从头开始重新读：

把 claude.desktop.inbox 里的所有消息从头读一遍

LLM 会调用：

mq9_fetch_messages(mail_address="claude.desktop.inbox", group_name="my-agent", reset_to="earliest")

mq9_ack_message

确认某条消息已处理。处理完消息后应该 ack，broker 会推进消费位点，下次 fetch 从 msg_id+1 开始。

参数：

参数	类型	必填	默认	说明
`mail_address`	string	是	-	mailbox 地址
`group_name`	string	是	-	消费组名（与 fetch 时保持一致）
`msg_id`	integer	是	-	消息 ID（来自 fetch 响应）

示例：

（fetch 之后）这条消息我处理完了，msg_id 是 5

LLM 会调用：

mq9_ack_message(mail_address="claude.desktop.inbox", group_name="my-agent", msg_id=5)

mq9_query_mailbox

查询 mailbox 中的消息（不影响消费位点，纯查看）。

参数：

参数	类型	必填	默认	说明
`mail_address`	string	是	-	mailbox 地址
`key`	string	否	-	按 key 精确过滤
`tags`	string[]	否	-	按 tag 过滤，消息须同时带有所有指定 tag
`since`	integer	否	-	Unix 时间戳（秒），返回该时间之后的消息
`limit`	integer	否	20	返回条数上限

示例：

看一眼 task.001.callback 里有什么消息，但不要消费

LLM 会调用：

mq9_query_mailbox(mail_address="task.001.callback")

按 tag 过滤：

查一下 agent.order.inbox 里标签是 billing 的消息

LLM 会调用：

mq9_query_mailbox(mail_address="agent.order.inbox", tags=["billing"])

mq9_register_agent

把自己注册到 mq9 注册中心，让其他 Agent 能发现。

参数：

参数	类型	必填	默认	说明
`name`	string	是	-	Agent 唯一名称
`payload`	string	是	-	能力描述（纯文本或 A2A AgentCard JSON 序列化成字符串）

示例：

把我注册成翻译助手，能力是中英互译，inbox 是 agent.translator.inbox

LLM 会调用：

mq9_register_agent(
  name="translation-agent-001",
  payload="{\"capabilities\":[\"zh-en translation\"],\"inbox\":\"agent.translator.inbox\"}"
)

mq9_discover_agents

查找具有特定能力的 Agent。

参数：

参数	类型	必填	默认	说明
`query`	string	否	-	自然语言查询或 `tag:xxx` 格式的 tag 查询
`limit`	integer	否	20	返回 Agent 数量上限

示例：

找一个会写 Python 代码的 Agent

LLM 会调用：

mq9_discover_agents(query="会写 Python 代码的 Agent")

按 tag 找：

找所有标签是 translation 的 Agent

LLM 会调用：

mq9_discover_agents(query="tag:translation")

mq9_unregister_agent

注销自己，从注册中心移除。建议 Agent 正常退出时调用。

参数：

参数	类型	必填	默认	说明
`name`	string	是	-	注册时使用的 Agent 名称

示例：

我要下线了，注销我自己

LLM 会调用：

mq9_unregister_agent(name="translation-agent-001")

典型场景

场景一：让 Claude 接收外部 Agent 发来的任务

对话示例：

用户：帮我创建一个 inbox 叫 claude.worker.inbox 然后注册我自己

Claude：[mq9_create_mailbox(name="claude.worker.inbox")]
[mq9_register_agent(name="claude-worker-001", payload="...")]
已经创建 inbox 并注册了你的身份。

用户：看看我的 inbox

Claude：[mq9_fetch_messages(mail_address="claude.worker.inbox", group_name="claude-worker-001")]
你有 3 条新消息：
1. 来自 user-agent-001：请帮我翻译这段...
2. 来自 task-coordinator：新任务分配...
3. 来自 monitor-agent：状态查询...

场景二：让 Claude 协调多个 Agent 完成任务

对话示例：

用户：我有一段中文需要翻译成英文然后总结成 100 字。

Claude：好的，让我找合适的 Agent。
[mq9_discover_agents(query="中英翻译")]
找到 agent.translator.inbox

[mq9_discover_agents(query="文本总结")]
找到 agent.summarizer.inbox

我会先发给翻译 Agent，再发给总结 Agent。
[mq9_send_message(mail_address="agent.translator.inbox", payload="...")]
[mq9_fetch_messages(mail_address="claude.worker.inbox", group_name="claude-worker-001")]
（等待翻译结果）
[mq9_ack_message(mail_address="claude.worker.inbox", group_name="claude-worker-001", msg_id=3)]
[mq9_send_message(mail_address="agent.summarizer.inbox", payload="<英文翻译>")]
[mq9_fetch_messages(mail_address="claude.worker.inbox", group_name="claude-worker-001")]
（等待总结结果）

最终结果：...

场景三：让 Claude 把当前会话状态广播给其他 Agent

用户：我们刚讨论的设计方案，发给所有架构相关的 Agent

Claude：[mq9_discover_agents(query="tag:architecture")]
找到 3 个架构相关 Agent：
- agent.architect.001
- agent.architect.002
- agent.reviewer.001

[mq9_send_message(mail_address="agent.architect.001", payload="<方案内容>")]
[mq9_send_message(mail_address="agent.architect.002", payload="<方案内容>")]
[mq9_send_message(mail_address="agent.reviewer.001", payload="<方案内容>")]

已发送给 3 个 Agent。

常见问题

Q1：`mailbox xxx does not exist` 怎么办

mailbox 不存在，先创建：

帮我创建 mailbox <name>

Q2：连接不上 broker

检查：

broker 是否启动（robustmq-server status）
8080 端口是否可访问（curl http://localhost:8080/health）
AI 工具配置里的 URL 是否正确
防火墙是否放行 8080 端口

Q3：Claude 不调用 mq9 工具

可能原因：

MCP 配置文件没生效（重启 AI 工具）
用户问题里没有明确通信意图，LLM 没识别出要用 mq9

可以直接说："用 mq9 帮我..."，引导 LLM 调用。

Q4：消息发出去对方收不到

检查：

对方 mailbox 名字是否正确
消息是否真的发出去了（用 mq9_query_mailbox 看 mailbox 里有没有）
对方 group_name 是否正确，位点有没有跳过

Q5：fetch 一直拿不到消息

可能原因：

mailbox 里确实没有新消息
group_name 设置错了（不同 group 各自维护位点）
消费位点已到达末尾（用 reset_to="earliest" 重置从头读）

Q6：删除消息

mq9 MCP 默认不暴露 delete 工具，避免误删。建议靠 TTL 自动清理，或使用 mq9 协议 CLI（robustmq-cli）手动删除。

Q7：怎么部署到生产环境

broker 部署在远程服务器，AI 工具配置 URL 改成远程地址（http://broker.example.com:8080/mcp）
启用 broker 认证后在 AI 工具 headers 里加 token
用 systemd 或 K8s 管理 broker 进程

Q8：多个 AI 工具能共用一个 broker 吗

可以。每个 AI 工具的 fetch/ack 调用中用不同的 group_name，broker 会独立维护各自的消费位点。多个 Agent 同时连接同一个 broker 是 mq9 的标准使用方式。

Q9：要不要专门为 MCP 开端口

不需要。MCP 端点挂在 broker 已有的 8080 HTTP 端口的 /mcp 路径，复用同一个 HTTP server，不需要单独开端口。

Q10：怎么关闭 MCP 能力

如果出于安全考虑想关闭 MCP，在 8080 HTTP server 配置里关闭 /mcp 路径——具体参考 RobustMQ 配置文档。MCP 关闭后 broker 其他能力不受影响。

反馈和支持

GitHub Issues：https://github.com/robustmq/robustmq/issues
文档：https://docs.robustmq.org/mq9
社区：见 RobustMQ 官网

如果遇到问题，提 Issue 时附上：

RobustMQ 版本（robustmq-server --version）
AI 工具和版本（如 Claude Desktop 0.7.0）
broker 端日志（mq9 协议错误 + MCP 端点错误）
复现步骤

mq9 MCP 使用手册 ​

简介 ​

前置条件 ​

快速开始 ​

1. 确认 broker 在运行 ​

2. 配置你的 AI 工具 ​

Claude Desktop ​

Cursor ​

Cline / Continue / 其他支持 HTTP MCP 的工具 ​

3. 验证连接 ​

关于 stdio 模式 ​

工具列表 ​

工具参考 ​

mq9_create_mailbox ​

mq9_send_message ​

mq9_fetch_messages ​

mq9_ack_message ​

mq9_query_mailbox ​

mq9_register_agent ​

mq9_discover_agents ​

mq9_unregister_agent ​

典型场景 ​

场景一：让 Claude 接收外部 Agent 发来的任务 ​

场景二：让 Claude 协调多个 Agent 完成任务 ​

场景三：让 Claude 把当前会话状态广播给其他 Agent ​

常见问题 ​

Q1：mailbox xxx does not exist 怎么办 ​

Q2：连接不上 broker ​

Q3：Claude 不调用 mq9 工具 ​

Q4：消息发出去对方收不到 ​

Q5：fetch 一直拿不到消息 ​

Q6：删除消息 ​

Q7：怎么部署到生产环境 ​

Q8：多个 AI 工具能共用一个 broker 吗 ​

Q9：要不要专门为 MCP 开端口 ​

Q10：怎么关闭 MCP 能力 ​

反馈和支持 ​

mq9 MCP 使用手册

简介

前置条件

快速开始

1. 确认 broker 在运行

2. 配置你的 AI 工具

Claude Desktop

Cursor

Cline / Continue / 其他支持 HTTP MCP 的工具

3. 验证连接

关于 stdio 模式

工具列表

工具参考

mq9_create_mailbox

mq9_send_message

mq9_fetch_messages

mq9_ack_message

mq9_query_mailbox

mq9_register_agent

mq9_discover_agents

mq9_unregister_agent

典型场景

场景一：让 Claude 接收外部 Agent 发来的任务

场景二：让 Claude 协调多个 Agent 完成任务

场景三：让 Claude 把当前会话状态广播给其他 Agent

常见问题

Q1：`mailbox xxx does not exist` 怎么办

Q2：连接不上 broker

Q3：Claude 不调用 mq9 工具

Q4：消息发出去对方收不到

Q5：fetch 一直拿不到消息

Q6：删除消息

Q7：怎么部署到生产环境

Q8：多个 AI 工具能共用一个 broker 吗

Q9：要不要专门为 MCP 开端口

Q10：怎么关闭 MCP 能力

反馈和支持