/ 目錄 / 演練場 / 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 or 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 介面

結果: 你可以看到和 Claude 完全相同的內容 — 只在 Claude 中才能重現的 bug 在這裡也會顯現。

注意事項
  • 伺服器將日誌輸出到 stdout,導致 JSON-RPC 串流損壞 — 將所有日誌導向 stderr。mcptools 會顯示這個問題 — 線索是出現 JSON 解析錯誤亂碼
  • 工具結構描述使用了不支援的 JSON Schema 關鍵字 — 堅持使用核心 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
    在 Claude 的 mcpServers 設定中配置 mcp proxy serve✓ 已複製
    → Claude 可以呼叫 disk_usage 並取得 df 的輸出

結果: 零程式碼的 MCP 工具,適合快速自動化任務。

注意事項
  • 暴露不受限制的 shell 是個危險的做法 — 使用 mcp guard 將特定指令加入白名單;絕對不要暴露 bash -c

使用 mcptools guard 對上游 MCP 強制執行允許/拒絕策略

👤 使用第三方 MCP 且重視資安的團隊 ⏱ ~20 min advanced

何時使用: 你信任 GitHub MCP 的讀取操作,但不希望代理程式建立 Issue 或刪除分支。

步驟
  1. 撰寫策略
    建立一個 guard 策略,允許 list_*get_* 工具,但拒絕 github 伺服器上的所有其他操作。✓ 已複製
    → 帶有明確規則的策略檔案
  2. 執行 guard
    執行 mcp guard --policy ./policy.yaml -- npx -y @modelcontextprotocol/server-github,並將 Claude 指向 guard 而非直接指向伺服器。✓ 已複製
    → 被拒絕的呼叫回傳明確的錯誤,允許的呼叫則正常代理

結果: 在強大伺服器前建立一個唯讀的外觀層 — 更安全的預設行為。

組合

與其他 MCP 搭配,撬動十倍槓桿

mcptools + hyper

在將 hyper-mcp 插件接入 Claude 之前,先用 mcp shell 對插件載入過程進行除錯

Use mcp shell to list plugins on my hyper-mcp host and test-call each tool.✓ 已複製
mcptools + claude-code

使用 mcp tools 驗證 Claude Code 設定中的每個 MCP 伺服器

For each server in ~/.claude.json, run mcp tools to verify it starts and advertises a non-empty tool list.✓ 已複製

工具

此 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 數
N/A (not an MCP itself)
費用
免費,MIT 授權
提示
使用 --format json | jq 在 CI 中自動化檢查流程

安全

權限、密鑰、影響範圍

憑證儲存: 憑證會直接傳遞給被代理的伺服器;mcptools 本身不儲存任何資料
資料出站: 僅限被代理或被保護的伺服器所傳輸的資料

故障排查

常見錯誤與修復

`mcp tools` hangs forever

伺服器將日誌輸出到 stdout,導致握手過程損壞。請將伺服器日誌重新導向至 stderr

驗證: mcp tools --timeout 5s -- <cmd>
Binary not found after `go install`

確認 $GOPATH/bin 已加入你的 PATH 環境變數

驗證: which mcp
Guard policy matches nothing

策略中的名稱必須與工具名稱完全一致(區分大小寫)。請先用 mcp tools 確認工具名稱

替代方案

mcptools 對比其他方案

替代方案何時用它替代權衡
MCP Inspector你偏好圖形介面,且可以接受在本機執行一個網頁應用程式較為笨重;可腳本化的程度不如 CLI
Raw jsonrpc via stdio你正在深入除錯一個協定層級的問題較為繁瑣;mcptools 已幫你處理握手流程

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills