/ 目录 / 演练场 / mcptools
● 社区 f ⚡ 即开即用

mcptools

作者 f · f/mcptools

MCP 开发者的瑞士军刀——CLI 工具,用于检查、调用、模拟、代理和守护任何 MCP 服务器。

mcptools(f/mcptools)是一个 Go CLI,用于通过 stdio、HTTP 或 SSE 与 MCP 服务器交互。用它来列出服务器上的工具、临时调用它们、启动用于测试的模拟服务器、将 shell 脚本包装为 MCP 工具,或通过 guard 执行访问策略。简单来说,就是 MCP 生态系统的 curl + jq + mitmproxy。

为什么要用

核心特性

实时演示

实际使用效果

mcptools.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcptools": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/f/mcptools"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcptools": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/f/mcptools"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcptools": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/f/mcptools"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcptools": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/f/mcptools"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcptools",
      "command": "TODO",
      "args": [
        "See README: https://github.com/f/mcptools"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mcptools": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/f/mcptools"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add mcptools -- TODO 'See README: https://github.com/f/mcptools'

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: mcptools

如何使用 mcptools 调试 MCP 服务器

👤 MCP 服务器开发者 ⏱ ~15 min intermediate

何时使用: 你的 MCP 在 Claude Desktop 中有时工作但有时无声地失败——你需要看到原始的传输流量。

前置条件
  • 安装了 mcptools — 通过 brew install f/mcptools/mcp 或 go install github.com/f/mcptools/cmd/mcp@latest
步骤
  1. 列出服务器上的工具
    运行 mcp tools --transport stdio -- node ./my-server.js。检查工具名称和模式。✓ 已复制
    → 干净的列表;如果为空,说明服务器没有正确地宣传工具
  2. 用原始参数调用特定工具
    运行 mcp call my_tool --params '{"x":1}' -- node ./my-server.js 并检查 JSON 响应。✓ 已复制
    → 工具输出与预期的模式匹配
  3. 启动交互式 shell
    运行 mcp shell -- node ./my-server.js 并手动调用工具。✓ 已复制
    → REPL,支持对你的工具的 tab 完成

结果: 你会看到 Claude 看到的一切——只在 Claude 中重现的错误在这里变得可见。

注意事项
  • 服务器向 stdout 输出日志,破坏了 JSON-RPC 流 — 将所有日志路由到 stderr。mcptools 会显示这一点——提示是 JSON 解析错误或乱码
  • 工具模式使用了不支持的 JSON Schema 关键字 — 坚持使用 core draft-07;某些客户端会拒绝 $refallOf 等。

模拟 MCP 服务器以测试 MCP 客户端

👤 客户端开发者 ⏱ ~20 min intermediate

何时使用: 你的 CI 不应该依赖真实的 Sentry/GitHub 服务器——你需要一个确定性的模拟。

步骤
  1. 编写模拟规范
    创建 ./mock.yaml,列出你想要伪造的工具和预设响应。✓ 已复制
    → YAML 描述工具名称和输出模板
  2. 运行 mcp mock
    运行 mcp mock --config ./mock.yaml --transport stdio 并将你的客户端指向它。✓ 已复制
    → 客户端看到一个完整的工具列表;调用返回预设数据

结果: 密闭的测试在离线 CI 上通过。

将 shell 命令公开为 MCP 工具,无需编写服务器

👤 运维人员、DIY 爱好者 ⏱ ~10 min beginner

何时使用: 你有一个好用的 shell 脚本,想让 Claude 调用它——但编写完整的 MCP 服务器感觉太麻烦了。

步骤
  1. 包装脚本
    运行 mcp proxy register disk_usage --command 'df -h' 并确认它已被宣传。✓ 已复制
    → 工具 disk_usage 已注册
  2. 将 Claude 指向 mcp proxy
    mcp proxy serve 配置 Claude 的 mcpServers。✓ 已复制
    → Claude 可以调用 disk_usage 并获得 df 输出

结果: 零代码 MCP 工具,用于快速自动化。

注意事项
  • 暴露无限制的 shell 是自杀式的 — 使用 mcp guard 来白名单特定命令;永远不要暴露 bash -c

使用 mcptools guard 在上游 MCP 上强制执行允许/拒绝策略

👤 使用第三方 MCP 的安全意识强的团队 ⏱ ~20 min advanced

何时使用: 你信任 GitHub MCP 的读取操作,但不想让代理创建问题或删除分支。

步骤
  1. 编写策略
    创建一个 guard 策略,允许 GitHub 服务器上的 list_*get_* 工具,但拒绝其他所有内容。✓ 已复制
    → 带有显式规则的策略文件
  2. 运行 guard
    运行 mcp guard --policy ./policy.yaml -- npx -y @modelcontextprotocol/server-github 并将 Claude 指向 guard 而不是直接指向服务器。✓ 已复制
    → 拒绝的调用返回清晰的错误,允许的调用代理通过

结果: 在强大的服务器前面的只读外观——更安全的默认值。

组合

与其他 MCP 搭配,撬动十倍杠杆

mcptools + hyper

在将其连接到 Claude 之前,使用 mcp shell 调试 hyper-mcp 插件加载

使用 mcp shell 在我的 hyper-mcp 主机上列出插件并测试调用每个工具。✓ 已复制
mcptools + claude-code

使用 mcp tools 验证你的 Claude Code 配置中的每个 MCP 服务器

对于 ~/.claude.json 中的每个服务器,运行 mcp tools 来验证它启动并宣传非空工具列表。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
mcp tools --transport <stdio|http|sse>, -- <server-cmd> 检查服务器的接口 0
mcp call <tool-name> --params '<json>' -- <server-cmd> 在没有客户端的情况下进行临时调用 1 tool call
mcp shell -- <server-cmd> 探索性调试 0
mcp mock --config <yaml> CI / 客户端测试 0
mcp proxy register <name> --command '<shell>'; serve 在没有代码的情况下将 shell 包装成 MCP 0
mcp guard --policy <yaml> -- <server-cmd> 对上游应用允许/拒绝 0

成本与限制

运行它的成本

API 配额
无——本地 CLI
每次调用 Token 数
不适用(本身不是 MCP)
费用
免费,MIT 许可
提示
使用 --format json | jq 在 CI 中自动化检查

安全

权限、密钥、影响范围

凭据存储: 传递到代理的服务器;mcptools 本身不存储任何内容
数据出站: 仅在代理/守护服务器所在的地方

故障排查

常见错误与修复

`mcp tools` 永远挂起

服务器向 stdout 写日志,破坏了握手。将服务器日志重定向到 stderr

验证: mcp tools --timeout 5s -- <cmd>
执行 `go install` 后找不到二进制文件

确保 $GOPATH/bin 在你的 PATH 中

验证: which mcp
Guard 策略不匹配任何内容

策略名称必须完全匹配工具名称(区分大小写)。首先使用 mcp tools 来确认名称

替代方案

mcptools 对比其他方案

替代方案何时用它替代权衡
MCP Inspector你更喜欢 GUI,并且愿意运行本地 web 应用更重;比 CLI 的可脚本性更差
Raw jsonrpc via stdio你在深度调试协议问题冗长;mcptools 为你处理握手

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills