mcptoon

社区

零依赖 MCP 客户端：工具发现从 71,929 tokens 降到 581（−99.2%，实测）

分类: 开发工具第 192 / 438
Stars: ★ 417 非常热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Python
凭据: 无需凭据
许可证: Apache-2.0
最近提交: 1 天前

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 官方项目。

最强项 · 安装易用性 13/20 最弱项 · 可靠性 8/20

可靠性

8/20

安全与权限

10/20

维护活跃度

11/20

文档质量

13/20

安装易用性

13/20

查看各项评分依据

可靠性 8/20: 静态证据显示该项目自述为纯标准库、零依赖的 CLI（156KB，23 个模块，13,415 行），并宣称 931 个测试通过、附带 CI 徽章，README 给出了可复现的命令行输出样例与 tiktoken 基准文件路径。但本次评审仅读取源文件、未执行任何代码，无法独立验证握手、工具列表与实际行为是否一致；README 中大量不可核实的量化断言（71,929→581 tokens、41/41 调用准确率、'官方基准'）属于未经第三方验证的自报数据，且存在自相矛盾之处（'measured' 与 'your mix will differ' 并存，demo 表第一段只有 19% 节省却与 99.2% 并列展示）。错误处理、超时、失败回退等边界情况在可见材料中没有充分证据，依赖可控性虽声称零依赖但无锁定与审计记录。按静态校准，缺乏可验证执行证据不高于 12 分，故扣分至 8。
安全与权限 10/20: 可见材料声明三层防护（破坏性操作需 --destructive、提示注入扫描、凭据泄漏检测）、无遥测、无守护进程、无存储凭据、无监听端口，权限边界与数据流描述较为清晰，未发现恶意代码、隐蔽外传、默认不可逆删除/支付/部署或硬编码真实令牌等红线行为，因此不触发 0-4 红线区间。但所有安全声明均来自 README 自述，无源代码级证据可核实；破坏性操作拦截至多依赖模式匹配，绕过风险未披露；'扫描结果中的注入模式'与'凭据泄漏检测'的误报/漏报率、作用范围、是否可关闭均无说明；连接 npm/pip/URL 外部服务器的网络与供应链侧写不完整。证据不足即为扣分项，故给 10 分而非满分。
维护活跃度 11/20: 许可证为 Apache-2.0，版本号规范（0.7.16），manifest 与 README 版本一致，有 CI 徽章、测试徽章、NOTICE 与第三方归属声明，话题与生态（ToonDeck、插件、技能）显示持续投入，201 star、1 个未关闭 issue 说明仓库活跃。但静态视角下无法确认提交频率、发布节奏、issue 响应时长、安全响应渠道（无 SECURITY.md 证据）与依赖更新路径；版本仍在 0.x，兼容性承诺（MCP 2026-07-28、Agent Plugins 1.0.0、skills、TOON v4.1）多处引用无法核实的前瞻规范，治理与版本演进策略存在空白。给 11 分。
文档质量 13/20: 文档层次丰富：安装命令、demo 验证、各命令清单、四种输出格式对照表、token 双账单拆解、与 Anthropic/MuleSoft 等方案的横向比较、安全说明、贡献与测试指引、开发者文档与中文版本链接均齐备，并给出 tiktoken 基准文件与浏览器计算器链接，示例具体可复现。扣分点在于：核心收益数字全部自报且无第三方复现，部分表述相互矛盾（'measured' 与可自行计算并存、'compact 默认就是最省' 与 '--slim 为原创' 的定位混乱）；没有逐工具的完整参数文档、错误码表、限额与配额说明；兼容性声明引用了超前于现实的规范版本（2026-07-28），可信度存疑；故障排查章节虽有 doctor/quickstart 但缺少已知问题与限制清单。故给 13 分。
安装易用性 13/20: 安装路径清晰且短：pip install 或 uvx 零安装 demo，PyPI 包信息与 server.json 中 pypi/stdio 传输声明一致，并提供 MCP 客户端配置示例（Claude Code 插件市场、skills add、sync 写入各 agent 原生 JSON、MCPTOON_AGENT_TYPE 环境变量），主流客户端覆盖 Claude Code/Cursor/Codex/Cline 等，平台兼容性有 Windows/Python 3.12 输出示例。扣分点在于：多个声明为可选的高级路径（插件自动安装、SessionStart hook、serve 桥接、ToonDeck GUI、Agent Plugins）未经执行验证，配置合并与冲突处理、Node 缺失时的降级、不同 agent 配置文件位置的差异均无细节；零安装演示依赖 uvx 与网络拉取。静态校准下无执行证据不高于 15 分，取 13 分。

静态评测 · 未实际运行收录于 2026-09-18

查看 FMRS 评分方法 →

选型与风险

能访问什么执行命令或代码访问网络

适合谁

配置了大量 MCP server、上下文预算紧张的 MCP 重度用户
同时使用多个 CLI/IDE agent，希望只维护一份工具配置的开发者
允许 agent 直接执行 shell 命令的团队（这是使用 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 自主添加并调用工具（无人工介入）在便利性提升的同时会扩大可被误用的操作面

安装接入

准备工作

运行环境：Python

其他可选配置项（1 个）

MCPTOON_AGENT_TYPE 可选设置智能体类型（如 claude 或 openai），使调用结果自动选择 --toon 或 JSON 输出格式。

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 安装插件。

验证是否装好

运行 mcptoon demo --quick（零安装、无需 API key），若能看到 71,929 → 581 令牌的基准表并成功调用一个工具，说明安装正常；或运行 mcptoon manifest 查看工具名列表。

常见排障

先运行 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 命令的能力

试试这样问

连接成功后，可以直接对 AI 助手这样说：

运行 mcptoon manifest，列出所有已配置 MCP 服务器的工具名称
用 mcptoon call everything echo '{"message":"hi"}' 调用 echo 工具测试连接
运行 mcptoon quickstart 自动发现本机已有的 MCP 服务器并生成配置
运行 mcptoon demo --quick 在本机验证令牌压缩效果

使用场景

把大量 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部分支持

依据项目文档列出，未经本站实测。

详细介绍

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 两种桥接模式，并内置危险操作拦截、提示注入扫描和凭据泄露检测三层防护。