MCP 服务器

使用 ccmux 的 MCP 服务器，让编码代理查看会话、读取项目笔记和检查用量。只有启用修改操作后，才能创建会话、发送按键或终止会话。

ccmux v0.3.0 及后续版本均包含该服务器程序。 安装 ccmux 后，请确保守护进程已运行，再连接客户端。

接入配置

在 Claude Code 中，为当前用户注册一个本地 stdio 服务器：

claude mcp add --transport stdio --scope user ccmux -- ccmux-mcp

运行 /mcp 可在 Claude Code 内检查连接。配置作用域和故障排查方法请参阅 Claude Code 的 MCP 文档 。

如需项目级配置，请使用 .mcp.json ，并将其放在项目根目录：

{
  "mcpServers": {
    "ccmux": { "command": "ccmux-mcp" }
  }
}

其他 MCP 客户端各有自己的配置格式。请添加一个 stdio 服务器，将命令设为 ccmux-mcp；如果客户端无法通过 PATH 找到程序，请使用其绝对路径。

代理现在可以使用这些工具：

这些工具均为只读，提供已连接守护进程可访问的信息。

允许代理执行操作

添加 --allow-mutate 到服务器参数中。项目级 Claude Code 配置示例如下：

{
  "mcpServers": {
    "ccmux": { "command": "ccmux-mcp", "args": ["--allow-mutate"] }
  }
}

即可解锁：

默认关闭是有原因的：能够向你的工作环境执行 send_keys 的代理，可以输入你能输入的任何内容。此参数表示主动启用。不支持逐工具覆盖；只能整体启用或关闭所有修改工具。

未设置此参数时，修改工具不会出现在 tools/list中。修改参数后，请通过客户端重启 MCP 服务器。

控制远程机器

CCMUX_HOST=mini.tail-xxxxx.ts.net:7474 ccmux-mcp
# or
ccmux-mcp --host mini.tail-xxxxx.ts.net:7474

代理在本地运行，查询 Mac mini 上的守护进程。修改工具仍需启用 --allow-mutate。协议和工具相同，只是通过 Tailscale HTTP 连接，而非本地 Unix 套接字。适合在笔记本上编码，同时查看 mini 上运行的长时间任务。

实际用途

几个具体场景：

多会话协调。 一个会话中的代理在另一个会话中启动助手（spawn_session ，位于不同项目），完成后读取输出（read_pane），取回结果并终止助手，全程无需人工介入。

跨机器协作。 笔记本上的代理检查 Mac mini 上另一个代理的进度（list_sessions, read_pane），无需你手动 SSH 登录。也可以在 mini 上启动耗时构建（spawn_session ，需先为 MCP 服务器配置 --host 和 --allow-mutate），然后继续本地工作。

项目记忆。 代理在会话开始时读取项目笔记（list_notes + read_note），避免重复之前代理完成的工作。笔记是磁盘上的普通 Markdown 文件，代理无需了解存储细节。

费用感知。 启动大型任务前，代理检查 get_usage ，了解本周费用，并通过 get_daemon_health 查看当前运行的会话数量。

这些都不需要新增基础设施，ccmux 已具备全部能力。MCP 只是让代理可以访问这些能力的协议。

安全模型

• 传输。 使用 stdio。守护进程的 Unix 套接字限定当前用户；tailnet HTTP 要求设备位于你的 tailnet 中。
• 修改操作。 默认关闭，需通过参数开启。
• 有限读取。 read_pane 最多返回 500 行，避免有缺陷的代理反复请求全部回滚记录而拖垮守护进程。
• 单次调用超时。 每个处理器的上下文期限为 30 秒。

当前限制

服务器提供请求与响应式工具，暂不支持实时订阅、逐工具修改权限和提示词库。

相关指南

• 配置远程主机 ，再连接其守护进程。
• 阅读 HTTP API 参考 ，直接基于 ccmuxd 构建客户端。

发现错误或过时内容？ 在 GitHub 上编辑此页.