Skip to main content
Glama

Claude MCP

Claude MCP 是一个跨平台桌面软件,用 Tauri 2、Rust、React 和 TypeScript 构建。它在本机启动一个 MCP Streamable HTTP 服务,让 Codex 等 MCP 客户端可以在不安装 Claude Code CLI 的情况下,把任务交给 Claude Agent SDK 执行。

默认 MCP 地址是:

http://127.0.0.1:8765/mcp

适合做什么

  • 让 Codex 调用一个本地 Claude Agent。

  • 使用 Claude Code 同源的 Agent 能力读写文件、搜索项目、修改代码和执行命令。

  • 通过 job_id 找回 Agent SDK session,继续让 Claude 修改上一轮任务的细节。

  • 查看每次 MCP 请求、上游 API 调用、本地工具执行和错误日志。

  • 统计每天的 input、output、cache read、cache write 和 total token。

Related MCP server: mcp-codex-dev

下载和安装

安装包在 GitHub Releases:

https://github.com/lizhipay/claude-mcp-server/releases

按系统选择安装包:

系统

架构

文件

macOS

Apple Silicon

Claude.MCP_*_aarch64.dmg

macOS

Intel

Claude.MCP_*_x64.dmg

Windows

x64

Claude.MCP_*_x64-setup.exe

Windows

ARM64

Claude.MCP_*_arm64-setup.exe

Linux

x64

Claude.MCP_*_amd64.AppImageClaude.MCP_*_amd64.deb

Linux

ARM64

Claude.MCP_*_aarch64.AppImageClaude.MCP_*_arm64.deb

macOS 当前使用临时签名,没有 Apple Developer ID 公证。如果系统提示无法验证开发者,可以右键打开;如果仍被拦截,可以执行:

xattr -dr com.apple.quarantine "/Applications/Claude MCP.app"

首次配置

打开 Claude MCP 后,在主控台填写:

字段

示例

说明

API 地址

https://api.anthropic.com

可以填根地址,也可以填完整 /v1/messages

API Key

sk-ant-...

保存到本机应用配置文件,不会在界面和日志里明文展示

模型名称

claude-opus-4-7

默认值就是 claude-opus-4-7

端口

8765

服务只监听 127.0.0.1

保存后点击“测试连接”。测试通过后点击“启动服务”,主控台会显示:

http://127.0.0.1:8765/mcp

健康检查地址是:

http://127.0.0.1:8765/health

Agent 内核

默认内核是官方 @anthropic-ai/claude-agent-sdk。它使用 Claude Code 同源的 agent loop、工具、上下文管理、session、hooks 和权限系统;安装包会携带 Agent SDK native binary,不需要用户单独安装 Claude Code CLI。

Claude MCP 仍保留 legacy 内核作为兜底。如果 Agent SDK bridge 在当前机器上无法启动,任务会自动切回 legacy,并在运行日志里写清楚原因。普通用户不需要手动切换。

开发环境需要先执行:

npm install

然后使用:

npm run dev

在 Codex 里添加 MCP

启动 Claude MCP 服务后,在终端执行:

codex mcp add claude-mcp --url http://127.0.0.1:8765/mcp

检查是否添加成功:

codex mcp list
codex mcp get claude-mcp

也可以手动写入 ~/.codex/config.toml

[mcp_servers.claude-mcp]
url = "http://127.0.0.1:8765/mcp"
enabled = true

添加后重新打开一个 Codex 线程。如果 MCP 连接成功,Codex 里会出现类似下面的工具名:

mcp__claude_mcp__code
mcp__claude_mcp__code_start
mcp__claude_mcp__code_status
mcp__claude_mcp__code_result
mcp__claude_mcp__code_continue_start

实际显示名称由 Codex 决定,但工具本体来自 claude-mcp

MCP 工具

Claude MCP 对外提供这些工具:

工具

用途

code

同步执行一个任务;超过约 90 秒会返回 job_id

code_with_context

带指定文件内容执行任务

code_start

启动异步任务,立刻返回 job_id

code_with_context_start

带指定文件内容启动异步任务

code_async

code_start 的别名

code_with_context_async

code_with_context_start 的别名

code_status

查询任务状态和最近输出

code_result

读取已完成任务的最终结果

code_wait

等待单个任务完成,超时才返回当前状态

code_batch_wait

一次等待多个任务完成,减少频繁轮询

code_batch_result

一次读取多个任务结果,不等待

code_batch_poll

增量读取多个任务的新完成结果

code_continue_start

按历史 job_id 继续同一段 Agent SDK session,立刻返回新的 job_id

code_continue

按历史 job_id 续聊并等待新任务结果

code_chat_history

查看一个 job_id 所属的轻量聊天记录和是否还能续聊

code_cancel

取消排队中或运行中的任务

推荐用法:

  • 短任务直接用 code

  • 长任务用 code_start 启动,再用 code_wait 等待结果。

  • 多任务并发用多个 code_start 启动;想一次等完用 code_batch_wait,想边完成边处理用 code_batch_poll

  • 已完成任务需要继续改细节时,用 code_continue_start 或桌面端“任务”页。

  • 不建议让 Codex 每隔几秒反复调用 code_status,除非只是临时查看进度。

任务状态包括:

queued
running
succeeded
failed
cancelled

codecode_start 参数:

{
  "prompt": "要交给 Claude 执行的任务",
  "workdir": "/Users/zoe/Developer/project"
}

code_with_contextcode_with_context_start 参数:

{
  "prompt": "基于这些文件修改代码并运行测试",
  "files": ["src/App.tsx", "src/styles.css"],
  "workdir": "/Users/zoe/Developer/project"
}

code_status 参数:

{
  "job_id": "返回的 job_id",
  "recent_chars": 8000
}

code_resultcode_cancel 参数:

{
  "job_id": "返回的 job_id"
}

code_wait 参数:

{
  "job_id": "返回的 job_id",
  "timeout_seconds": 90,
  "recent_chars": 8000
}

code_batch_wait 参数:

{
  "job_ids": ["job_id_1", "job_id_2"],
  "timeout_seconds": 90,
  "recent_chars": 4000
}

code_batch_result 参数:

{
  "job_ids": ["job_id_1", "job_id_2"],
  "recent_chars": 4000
}

code_batch_poll 参数:

{
  "job_ids": ["job_id_1", "job_id_2"],
  "seen_job_ids": [],
  "timeout_seconds": 3,
  "recent_chars": 4000,
  "include_running": false
}

code_waitcode_batch_wait 是阻塞等待工具。它们内部使用任务完成通知,不是固定间隔轮询;任务完成会立刻返回,超时才返回当前状态。

code_batch_poll 用于批量任务的增量读取:每次只返回还没处理过的完成、失败、取消或找不到的任务。Codex 需要把返回的 next_seen_job_ids 保存下来,下次作为 seen_job_ids 继续传入。

code_batch_poll 一次最多接收 500 个 job_id,适合几百个并发任务分批读取。

code_continue_start 参数:

{
  "job_id": "历史 job_id",
  "prompt": "继续修改:把按钮颜色调浅一点,并保持现有风格",
  "workdir": "/Users/zoe/Developer/project"
}

workdir 可以不填;不填时会继续使用这段 session 原来的目录。

code_continue 参数:

{
  "job_id": "历史 job_id",
  "prompt": "继续修改:补一组测试覆盖这个边界",
  "timeout_seconds": 180,
  "recent_chars": 8000
}

code_chat_history 参数:

{
  "job_id": "任意历史 job_id",
  "limit": 20
}

code_chat_history 会返回 codex_context。这是给 Codex 看的轻量上下文,包含历史 prompt、Claude 最终回复、任务状态、目录和续聊建议;完整上下文仍由 Agent SDK session 保存,不需要塞进 prompt。

续聊能力依赖 Agent SDK session。默认保留 30 天;如果任务来自 legacy 内核、session 已过期、或同一段 session 还在运行,会返回明确错误。

在 Codex 里怎么用

这个软件最适合的用法是:Codex 做调度和验收,Claude MCP 负责真正写代码、改文件、跑命令。你可以把它当成一个本机 Claude Code Agent,Codex 只需要把任务交给 claude-mcp

推荐流程:

  1. 打开 Claude MCP,保存 API 配置,点击“启动服务”。

  2. 在 Codex 里确认已经添加 claude-mcp

  3. 新开一个 Codex 线程,把下面的提示词复制进去。

  4. Codex 调用 Claude MCP 写代码。

  5. Codex 读取结果、检查文件、跑必要验证。

给 Codex 的固定开场白

每次想让 Codex 调用这个软件时,可以先把这一段贴进去:

请优先使用 claude-mcp 来完成任务。

要求:
1. 需要写代码、改文件、跑命令的部分,交给 claude-mcp 执行。
2. 你负责监督进度、读取结果、检查产物和汇报结论。
3. 明确传入 workdir,不要让 claude-mcp 在错误目录里工作。
4. 长任务使用 code_start,然后用 code_wait 或 code_batch_poll 读取结果。
5. 如果工具列表里暂时看不到 mcp__claude_mcp__,先提醒我检查 Claude MCP 是否启动,不要假装已经执行。

最小可用测试

第一次连接时,用这个测试最简单:

请使用 claude-mcp 的 code 工具执行一个连通测试。

workdir: /tmp

任务:
返回一句话:Claude MCP 已经可以被 Codex 调用了。

期望结果:Codex 会调用 claude-mcp,然后返回 Claude MCP 的回答。如果 Codex 说工具不存在,通常是 Claude MCP 没启动、Codex 没重新打开线程,或 MCP 名字没有添加成功。

让 Claude MCP 修改一个项目

适合修 bug、加功能、改 README、做小页面:

请使用 claude-mcp 完成下面的代码任务。

workdir: /Users/zoe/Developer/your-project

任务:
1. 阅读项目结构。
2. 找到用户登录页面。
3. 修复登录失败时错误提示不明显的问题。
4. 保持现有 UI 风格,不要重构无关代码。
5. 修改完成后运行项目已有测试或最接近的检查命令。
6. 最终返回:修改了哪些文件、验证命令、验证结果。

执行方式:
- 用 code_start 启动任务。
- 用 code_wait 等待结果,timeout_seconds 设置为 300。
- 不要只给计划,必须让 claude-mcp 实际改文件。

继续上一轮任务

适合 Claude MCP 已经写完代码,但你还想继续让它调细节:

请使用 claude-mcp 继续上一轮任务。

历史 job_id: 粘贴上一轮返回的 job_id

继续要求:
1. 保持上一轮上下文和同一个 workdir。
2. 把页面里的保存按钮改得更醒目。
3. 不要重构无关代码。
4. 修改完成后运行上一轮同样的验证命令。

执行方式:
- 先用 code_chat_history 确认这个 job_id 是否 resumable,并阅读返回的 codex_context。
- 如果可续聊,用 code_continue_start 创建续聊任务。
- 用 code_wait 等待新的 job_id 完成。
- 最终只汇报新增修改和验证结果。

桌面端也可以直接打开“任务”页,选中历史任务后在右侧输入修改要求。

让 Claude MCP 写一个完整页面

适合把一个需求直接交给 Claude MCP 做完:

请使用 claude-mcp 写一个完整页面。

workdir: /Users/zoe/Developer/your-project

任务:
做一个订单列表页面,要求:
1. 能展示订单号、客户、金额、状态、创建时间。
2. 支持按状态筛选。
3. 支持搜索订单号和客户名。
4. 保持项目现有组件和样式习惯。
5. 如果需要新增文件,可以新增。
6. 完成后运行类型检查或构建命令。
7. 最终返回可访问路径、修改文件、验证结果。

执行方式:
- 使用 code_start。
- 如果超过 5 分钟还没完成,用 code_status 看最近输出。
- 完成后用 code_result 读取最终结果。

让 Claude MCP 做代码审查

适合让 Claude MCP 只读检查,不改文件:

请使用 claude-mcp 做一次代码审查。

workdir: /Users/zoe/Developer/your-project

任务:
1. 只读检查,不要修改文件。
2. 优先找会导致运行失败、数据错误、并发问题、安全问题或测试缺口的点。
3. 每个问题都要写清楚文件路径、原因和建议修复方式。
4. 如果没有发现明显问题,明确说没有发现阻塞级问题。

执行方式:
- 使用 code_start。
- 使用 code_wait 等待结果。

让 Claude MCP 自己启动服务

适合做小游戏、静态页面、Demo 项目:

请使用 claude-mcp 在下面目录里完成一个可运行 Demo。

workdir: /Users/zoe/Developer/ai/test

任务:
1. 做一个完整可玩的贪吃蛇游戏。
2. 二次元可爱风格。
3. 支持键盘方向键、WASD 和移动端触控。
4. 包含开始、暂停、重新开始、得分、最高分。
5. 写完后自己启动本地服务。
6. 服务只监听 127.0.0.1,端口任选可用端口。
7. 启动后用 curl 验证首页能访问。
8. 最终返回浏览器可以直接打开的 URL。

执行方式:
- 使用 code_start。
- 用 code_wait 等待结果。
- 如果服务被前台进程挂住,读取到 URL 后再让 claude-mcp 单独关闭服务。

多个任务并发处理

适合让 Claude MCP 同时做多件互不影响的事。Codex 负责启动任务和收结果:

请使用 claude-mcp 并发完成下面 3 个只读任务。

workdir: /Users/zoe/Developer/your-project

任务 A:
阅读 README.md,判断新用户能不能顺利启动项目。

任务 B:
阅读 package.json 和 src 目录,整理项目的构建、测试和开发命令。

任务 C:
阅读最近改动,找出可能缺少测试的地方。

执行方式:
1. 用 code_start 分别启动 3 个任务。
2. 保存返回的 job_id。
3. 维护 seen_job_ids = []。
4. 每 3 秒调用一次 code_batch_poll:
   {
     "job_ids": ["任务 A 的 job_id", "任务 B 的 job_id", "任务 C 的 job_id"],
     "seen_job_ids": seen_job_ids,
     "timeout_seconds": 3,
     "recent_chars": 4000
   }
5. 每次处理 completed / failed / cancelled / not_found。
6. 把返回的 next_seen_job_ids 保存为新的 seen_job_ids。
7. complete=true 后停止读取,合并结果给我。

并发修复多个独立问题

适合一个项目里有几处互不影响的小问题,想让 Claude MCP 分头处理:

请使用 claude-mcp 并发修复下面 4 个问题。

workdir: /Users/zoe/Developer/your-project

任务 1:
修复设置页保存成功后没有提示的问题。

任务 2:
修复列表页空状态文案不居中的问题。

任务 3:
检查移动端导航按钮文字是否溢出,必要时修复。

任务 4:
补充 README 里的本地启动说明。

执行方式:
1. 每个任务分别用 code_start 启动。
2. 每个任务都要求 Claude MCP 只改自己负责的文件,避免互相覆盖。
3. 用 code_batch_poll 每 3 秒读取新完成结果。
4. 如果某个任务失败,把失败原因单独用 code_continue_start 继续交给同一个 job 修。
5. 所有任务结束后,你再检查 git diff,确认没有互相打架。

指定文件让 Claude MCP 精准修改

适合你已经知道问题范围,不想让 Agent 在整个项目里乱翻:

请使用 claude-mcp 的 code_with_context_start 精准修改。

workdir: /Users/zoe/Developer/your-project

files:
- src/App.tsx
- src/styles.css
- src/App.test.ts

任务:
1. 只围绕这三个文件处理。
2. 修复弹窗关闭按钮在小屏幕下错位的问题。
3. 保持现有组件结构,不要重写页面。
4. 修改完成后运行 npm test 和 npm run build。
5. 最终返回改动摘要和验证结果。

执行方式:
- 用 code_with_context_start 启动。
- 用 code_wait 等待结果,timeout_seconds 设置为 300。

测试失败后继续修

适合 Claude MCP 第一次改完后测试没过,让它带着同一段上下文继续修:

请继续修复这个 Claude MCP 任务。

历史 job_id: 粘贴上一次失败任务的 job_id

失败信息:
把这里粘贴测试失败的关键报错。

继续要求:
1. 先用 code_chat_history 读取这个 job 的 codex_context。
2. 用 code_continue_start 继续同一个 Agent SDK session。
3. 只修复测试失败相关问题,不要扩大改动范围。
4. 修完后重新运行失败的测试命令。
5. 如果测试通过,再运行完整构建命令。

让 Claude MCP 做发布前检查

适合发版前让 Claude MCP 帮你做一次只读检查:

请使用 claude-mcp 做发布前检查,不要修改文件。

workdir: /Users/zoe/Developer/your-project

任务:
1. 检查 package.json、README、版本号、构建脚本是否一致。
2. 检查最近 git diff 是否包含明显调试代码、临时文件、无关改动。
3. 检查是否有应该补充到 README 的使用方式。
4. 给出发布风险清单,按严重程度排序。

执行方式:
- 用 code_start 启动。
- 用 code_wait 等待结果。
- Codex 收到结果后再决定是否执行发布。

让 Claude MCP 写测试

适合功能已经写完,但测试覆盖不够:

请使用 claude-mcp 给现有功能补测试。

workdir: /Users/zoe/Developer/your-project

任务:
1. 阅读最近 git diff。
2. 找出新增或变更的用户行为。
3. 按项目现有测试风格补充最小必要测试。
4. 不要为了测试大改业务代码。
5. 运行对应测试命令。
6. 最终返回新增测试覆盖了哪些行为。

让 Claude MCP 生成迁移说明

适合改了配置、接口、命令或用户使用方式之后:

请使用 claude-mcp 生成迁移说明。

workdir: /Users/zoe/Developer/your-project

任务:
1. 阅读 README、CHANGELOG 和最近 git diff。
2. 总结这次版本对用户有什么变化。
3. 写一段适合放到 GitHub Release 的说明。
4. 如果有破坏性变更,单独列出来。
5. 只修改 CHANGELOG.md;如果没有这个文件,就只返回建议内容,不要新建文件。

让 Codex 监督 Claude MCP 写完再验收

这是最推荐的真实工作提示词:

请把自己当成监督者,把写代码的工作交给 claude-mcp。

目标目录:
workdir: /Users/zoe/Developer/your-project

需求:
修复用户反馈的这个问题:保存按钮点击后没有任何提示。

执行要求:
1. 你不要直接改代码。
2. 调用 claude-mcp 的 code_start,让它检查项目、修改代码、运行验证。
3. 用 code_wait 或 code_batch_poll 读取结果。
4. Claude MCP 完成后,你再检查 git diff,确认改动范围合理。
5. 如果验证失败,把失败原因继续交给 claude-mcp 修。
6. 最后只汇报:改了什么、验证是否通过、还有没有风险。

常见情况怎么处理

情况

推荐做法

任务很短

code

任务可能超过 1 分钟

code_start + code_wait

同时启动很多任务

用多个 code_start + code_batch_poll

只想读结果,不等待

code_resultcode_batch_result

任务卡住

先用 code_status 看最近输出,再决定是否 code_cancel

Codex 说工具不存在

确认 Claude MCP 已启动,并重新打开 Codex 线程

Claude 在错误目录工作

提示词里写清楚绝对路径 workdir

Claude Agent 能使用的本地能力

默认 SDK 内核使用 Claude Code 的内置工具:

能力

说明

文件读取

读取 workdir 内相关文件

文件编辑

使用 Claude Code 的编辑能力修改文件

项目搜索

使用 Glob/Grep 等工具查找代码

命令执行

workdir 下执行开发命令

Todo / session

复用 Claude Code 的任务规划和上下文管理

legacy 内核仍保留旧工具:

legacy 工具

能力

read_file

读取 UTF-8 文件

write_file

写入 UTF-8 文件,必要时创建父目录

list_dir

列出目录内容

run_command

workdir 下执行命令

命令执行规则:

  • macOS 和 Linux 使用 sh -lc

  • Windows 使用 cmd /C

  • 默认超时 60 秒,最大 600 秒。

  • 命令输出会截断,避免日志和返回结果过大。

  • 服务只绑定 127.0.0.1,不会监听公网地址。

注意:只把可信目录作为 workdir。SDK 内核使用 bypassPermissions 完全放行模式,Claude 可以直接读写文件、执行命令和调用内置工具;Claude MCP 不再额外拦截危险命令或敏感路径。

日志

“运行日志”页显示当前进程内的请求记录,包括:

  • MCP 请求。

  • new-api 请求。

  • 流式返回事件。

  • 本地工具调用。

  • 文件读写。

  • 命令执行。

  • 错误和取消。

日志只存在内存里,不会写入文件。清空日志不会影响正在运行的任务。API Key 会脱敏显示。

用量统计

“用量统计”页会持久保存每日 token 记录,包含:

  • input tokens

  • output tokens

  • cache read tokens

  • cache write tokens

  • total tokens

  • request count

统计来源是上游 API 返回的 usage 字段。Claude MCP 会发送 cache_control 标记来请求缓存;如果上游没有返回 cache_read_input_tokenscache_creation_input_tokenscache_creation 字段,页面里的缓存读写会显示为 0。

API 地址规则

下面两种写法都可以:

https://api.example.com
https://api.example.com/v1/messages

最终请求都会发到:

https://api.example.com/v1/messages

请求头包含:

Authorization: Bearer <API_KEY>
anthropic-version: 2023-06-01

本地开发

环境要求:

  • Node.js

  • Rust

  • 系统对应的 Tauri 2 依赖

安装依赖:

npm install

启动开发版:

npm run dev

只构建前端:

npm run build

构建当前系统安装包:

npm run tauri -- build

运行测试:

npm test
cd src-tauri
cargo test

发布

推送 v* tag 会触发 GitHub Actions,并上传 macOS、Windows、Linux 的 x64 和 ARM64 安装包。

git tag v0.1.10
git push origin main v0.1.10

发布工作流文件:

.github/workflows/release.yml

常见问题

Codex 看不到 claude-mcp

确认 Claude MCP 主控台显示“运行中”,再执行:

codex mcp list
codex mcp get claude-mcp

如果刚添加完 MCP,重新打开一个 Codex 线程。

端口被占用

默认端口是 8765。如果启动失败,在主控台换一个 1024 以上的端口,然后重新执行:

codex mcp remove claude-mcp
codex mcp add claude-mcp --url http://127.0.0.1:8787/mcp

上面的 8787 换成你在主控台填写的新端口。

macOS 提示无法打开

当前安装包没有 Apple Developer ID 公证。可以右键打开,或执行:

xattr -dr com.apple.quarantine "/Applications/Claude MCP.app"

后台看不到缓存读写

缓存读写取决于上游是否支持并返回 Claude 兼容的缓存字段。Claude MCP 会发送缓存标记;如果上游没有返回缓存字段,本地统计和后台都可能显示为 0。

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    F
    maintenance
    An MCP server that integrates Codex CLI into Claude Code workflows for code writing, execution, and review with session management. It features real-time progress monitoring via a local HTTP dashboard and supports detailed configuration for various coding tools.
    6
    15
    166
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    An MCP server that bridges Claude Desktop and Claude Code by letting Desktop read and interact with Claude Code Remote Control sessions, enabling cross-agent coordination.
    6
    3
    MIT