适合谁
- 配置了大量 MCP server、上下文预算紧张的 MCP 重度用户
- 同时使用多个 CLI/IDE agent，希望只维护一份工具配置的开发者
- 允许 agent 直接执行 shell 命令的团队（这是使用 mcptoon 的前提）
- 关注供应链安全、偏好零依赖纯标准库工具的使用者
M
55FMRS · C
mcptoon 是一个定位清晰的 MCP 工具调度层：以 CLI 形态解决 MCP 工具 schema 挤占上下文、以及每个 agent 各自重复配置这两个真实痛点。核心数据来自项目自带基准（tiktoken cl100k_base，255 工具 71,929 → 581 tokens，−99.2%），项目亦引用 Anthropic、Firecrawl、Scalekit 等外部测算佐证「schema 全量注入成本高昂」这一行业共识。它的优点是零依赖、无守护进程、无遥测、不打包 server、可随时删除；局限在于使用前提是 agent 能执行 shell 命令，且不提供现成工具集，需用户自行安装 MCP server 并承担相应供应链风险。它不是 Anthropic 官方项目。
mcptoon 是一个 156KB 的 CLI 工具，本体零第三方依赖，用纯 Python 标准库实现。它把 MCP 工具 schema 挡在 agent 上下文窗口之外：默认只输出工具名索引，实测 255 个工具的发现成本从 71,929 tokens 降到 581 tokens（−99.2%）；调用结果加 --toon 可再省约 34%。它同时充当多 agent 的统一配置层：在 ~/.mcptoon/config.json 配置一次，凡是能执行 shell 命令的 agent（Claude Code、Cursor、Codex、脚本、CI）都能共用同一批 MCP server 与工具，新增工具无需重启 agent，也不用改每个 agent 的 JSON 配置。mcptoon 本身不打包任何 MCP server，它只是调度层：server 由用户自行按需安装（npm/pip/URL），空闲时不启动，删除 mcptoon 也不影响这些 server 继续独立运行。它面向 MCP 提供 stdio 与 HTTP 两种桥接模式，并内置危险操作拦截、提示注入扫描和凭据泄露检测三层防护。
安装接入
1) 安装：pip install mcptoon（纯标准库，156KB，零依赖）。2) 快速验证：运行 mcptoon demo --quick，它会启动官方 everything 参考 server 并打印 token 对比，无需 API key。3) 添加 MCP server：mcptoon add everything --stdio npx -y @modelcontextprotocol/server-everything，或 mcptoon install brave-search --npm @modelcontextprotocol/server-brave-search。4) 查看工具名索引：mcptoon manifest（默认 compact，255 个工具约 581 tokens）。5) 调用工具：mcptoon call everything echo '{"message":"hi"}'，加 --toon 可压缩结果。6) 多 agent 统一配置：mcptoon sync 把原生 JSON 写入各 agent 自己的配置位置；或运行 mcptoon quickstart 一次性完成发现、配置与列工具。7) Claude Code 用户可通过 /plugin marketplace add activeing123/mcptoon 安装插件。
选型与风险
不适合谁
- 无法执行 shell 命令的纯图形界面 agent（需依赖 mcptoon sync 写入原生配置）
- 期待开箱即得现成工具集的使用者——mcptoon 不打包任何 MCP server，需自行安装
- 需要托管式服务或云端控制面能力的场景
- 希望获得 Anthropic 官方支持的用户：mcptoon 是独立第三方 MCP 客户端，与 Anthropic 无隶属关系
所需权限
- 读写用户目录下的 ~/.mcptoon/config.json 配置文件
- 执行本机 shell 命令以启动/调用用户自行安装的 MCP server（如 npx、pip 启动的进程）
- 在 mcptoon sync 时写入各 agent 自身的原生配置文件位置
- 工作目录内的文件读写（如本地配置、日志、统计信息）
风险与副作用
- mcptoon 不启动守护进程，但它会为你启动你添加的第三方 MCP server，这些 server 自身的权限与风险由用户自行承担
- 按需添加 server 意味着供应链风险转移给用户所选用的 npm/pip 包，需自行甄别
- 内置的危险操作拦截（--destructive）、提示注入扫描与凭据泄露检测是防护层而非绝对保证，不能替代人工审查
- agent 自主添加并调用工具（无人工介入）在便利性提升的同时会扩大可被误用的操作面
常见排障
- 先运行 mcptoon doctor 做自检：检查 Python 环境、配置文件与连通性
- 工具列表为空或工具不出现：用 mcptoon list 确认 server 是否已配置，用 mcptoon manifest 检查工具索引，必要时 --full / --json 查看完整 schema
- 调用失败或返回格式异常：先去掉 --toon 用默认 JSON 输出对比，--toon 解码失败会自动回退 JSON（--fallback-json）
- agent 猜错参数导致调用无效：改用先 mcptoon inspect <server> <tool> 查看参数、再 mcptoon call 的流程
- 机器上没有 Node：改用 mcptoon demo-server（11 个标准库工具，无需下载、无需网络）
- 添加后 agent 仍看不到工具：执行 mcptoon sync 把配置写入该 agent 的原生位置，或确认该 agent 具备执行 shell 命令的能力
使用场景
把大量 MCP 工具接入 agent，但不想让完整 schema 占满上下文窗口
为机器上多个 AI agent（Claude Code、Cursor、Codex 等）统一配置同一批 MCP server
让 agent 在任务中途自行添加并调用新的 MCP 工具，无需人工改 JSON、无需重启
在无 Node 环境下用标准库自带的 11 个演示工具验证 MCP 调用流程
通过 mcptoon serve 把已配置的多个 server 收敛为单一 MCP 端点供给 agent
支持客户端
Claude Code完整支持
Cursor部分支持
Codex部分支持
Cline部分支持
Windsurf部分支持