MCP Inspector 完整教程：从零调试 MCP 服务器的终极指南
项目地址: https://gitcode.com/gh_mirrors/inspector1/inspector MCP Inspector 是一款免费的 MCP（Model Context Protocol）服务器可视化调试工具，它在一个 npm 包里提供了 Web、CLI、TUI 和 mcpdo 四种使用形态。无论你是第一次接触 MCP 协议的新手，还是需要做回归测试和 CI 验证的资深开发者，都可以用它直观地查看并调通一个服务器暴露的 Tools、Resources、Prompts 和日志。它的核心价值在于：连接一次，就能在六个标签页里完成「列清单 → 填参数 → 执行 → 看结果 → 回放」的完整调试闭环，同一套连接配置还能直接复用到自动化脚本里。
从零起步：三步启动 MCP 调试界面
用一条 npx 命令先跑通 Web 界面
- 确认本机已安装 Node.js（从源码本地调试要求
>= 22.19.0）。 - 在任意目录直接运行以下命令，浏览器会自动打开调试页面：
npx @modelcontextprotocol/inspector # Web 界面（默认）
npx @modelcontextprotocol/inspector --cli # 命令行客户端
npx @modelcontextprotocol/inspector --tui # 终端交互界面
- 看到服务器列表页即表示启动成功，接下来只需添加你的服务器即可开始调试。
本地开发：装好依赖再构建四个客户端
如果你想改代码或跟进最新版，先克隆仓库再构建：
git clone https://gitcode.com/gh_mirrors/inspector1/inspector
cd inspector && npm install
npm run build && npm run web
- 日常只改 Web 界面时，可以在
clients/web目录直接npm run dev，享受 Vite 的热更新，无需走 launcher 构建。 - 各客户端（web / cli / mcpdo / tui / launcher）的详细参数见各自目录下的 README，如 clients/web/README.md。
⚠️ 常见坑：Inspector 会管理 OAuth token 和 stdio 的
env:密钥。有系统 keychain 时默认存入 keychain；在 Linux 无 libsecret、容器或 SSH 会话里会明文落到~/.mcp-inspector/secrets.json。上生产环境前请阅读 docs/secret-storage.md，确认密钥存储位置并考虑加密。
看懂界面：调试主界面的三大区域
服务器列表页：状态、连接与配置一屏管理
首次启动后你看到的第一个界面就是服务器列表。每个服务器一张卡片，包含这些要素：
- 状态徽标：绿色
Connected表示已连接，红色Failed表示连接失败，旁边还会标出失败次数； - 传输类型：
STDIO（本地进程，填启动命令）或HTTP（远程 URL，可选 Direct / Via Proxy）; - 卡片操作：
Server Info、Settings、Test Client Features、Clone、Edit、Remove，右上角开关用于连接/断开。
功能标签页：六种调试视角快速切换
连接成功后进入主调试界面：顶部是 Tools、Resources、Prompts、Logs、Tasks、History 六个标签页，左上角显示当前服务器名与实时响应耗时，右上角是 Disconnect。把标签页理解成「同一个连接的六种查看角度」，排查问题时按需切换即可。
资源页：URIs、Templates 与 Subscriptions 分区浏览
Resources 标签页左栏分三段：URIs（静态资源列表，可搜索）、Templates（URI 模板，填好变量后点 Go 生成并读取）、Subscriptions（已订阅的更新流）；右栏展示选中资源的原始内容与 Last updated 时间戳。
核心实战：4 步完成一次完整工具调用
获取工具清单并选中目标工具
- 回到服务器列表页，打开目标服务器卡片右侧的开关，等待状态变为
Connected。 - 进入
Tools标签页，左栏会自动列出全部工具（如echo、add、longOp），支持Search tools...过滤和Refresh刷新。 - 点击工具名，中栏显示它的描述、
Annotations注解（如read-only）和参数表单。
填参数、执行，并观察返回的原始 JSON
- 在带
*的必填字段里填入测试内容（例如给message字段输入任意文本）。 - 点击
Execute Tool执行调用。 - 右侧
Results面板会渲染服务器返回的原始 JSON，可用Copy复制、Clear清空。
💡 实用技巧：长耗时工具（如
longOp）适合验证进度通知机制，执行期间切到Logs标签页，可以实时看到服务器推送的进度与日志消息，确认通知链路是否完整。
快速排障：连接失败与执行异常的自查清单
连接失败：按「命令 → 网络 → 鉴权」顺序检查
- STDIO 服务器：核对启动命令与参数拼写（
npx -y后面的包名写错是最常见原因），并确认本机 Node 版本满足要求。 - HTTP 服务器：卡片上会直接给出超时提示（如
Connection timeout after 20s），点Show more展开完整错误；再用浏览器或 curl 单独访问该 URL 确认网络可达。 - 鉴权类失败：OAuth 服务器需要完成授权同意页的跳转，检查是否被弹窗拦截；涉及 token 存取问题时参考 docs/secret-storage.md 与 specification/v2_auth.md。
工具执行报错：用 Logs 与 History 两个标签页定位
Logs标签页记录 stderr 输出与服务器通知，先确认错误来自服务器还是传输层；History标签页按时间记录每次请求的方法、状态（OK/Error）与耗时，Expand可展开完整请求/响应参数，对照「入参 → 报错」快速缩小范围。
效率进阶：多服务器并行与自动化回归
用 catalog 文件批量管理多套服务器配置
- 默认 catalog 位于
~/.mcp-inspector/mcp.json，在 Web 界面可直接增删改服务器；首次从源码启动 Web 时会预置 everything-server、filesystem-server 和远程 example-server 三个示例，开箱即连。 - 想读取同事或客户端应用写好的配置而不落盘修改时，改用
--config <path>（只读会话），它与--catalog互斥，详细规则见 docs/mcp-server-configuration.md。 - 想验证 MCP 协议各特性，仓库内置的可组合测试服务器覆盖了几乎所有功能，用法见 docs/test-servers.md。
回放与导出：把 History 变成回归验证工具
- 对任意请求点
Pin收入Pinned Requests，之后随时Replay一键重放，用于改动前后对比； - 点
Export JSON导出全部操作记录存档，或按Filter by method只看某类调用。
用 CLI 把调试流程搬进 CI
CLI 形态支持「连接 → 列清单 → 调用 → 断言」的脚本化流程，例如列出目标服务器的工具：
npx @modelcontextprotocol/inspector --cli \
--method tools/list node build/index.js
配合 --format json 做断言，就能在流水线里跑无人值守的冒烟测试，完整工作流与退出码说明见 docs/cli-smoke-testing.md。
MCP Inspector 把 MCP 服务器调试从「黑盒猜测」变成了可视、可回放、可脚本化的流程：界面给你即时反馈，History 和 CLI 让同样的验证可以反复执行。建议从默认的 Web 界面熟悉一遍主流程，再按团队场景选择 CLI 或 TUI 形态落地到日常开发中。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
