MCP Inspector 是 Model Context Protocol 官方生态中的开发者工具,以单一 npm 包提供 Web、CLI、TUI 和实验性 mcpdo 四种检查方式,覆盖交互调试、脚本化测试、终端操作与多命令连接复用。它默认将 OAuth 令牌、客户端密钥和 stdio 环境变量存入系统钥匙串,并针对 CI 与 agent 反馈循环做了专门设计,是调试 MCP 服务器的高效入口。
适用人群:MCP服务器开发者与协议实现者;需要将MCP测试接入CI的DevOps与平台工程师;在终端、远程或容器环境中工作的AI应用开发者
适用场景:本地调试MCP服务器的连接与能力;在CI中执行脚本化回归测试并形成快速agent反馈循环;通过mcpdo对命名连接执行多条命令的工作流
推荐理由:如果你正在开发或维护 MCP 服务器,Inspector 值得优先尝试。它把 Web 可视化、CLI 自动化、TUI 终端交互和连接复用统一在一个包中,既适合日常排查,也能接入 CI。官方维护、文档透明,密钥存储策略清晰,能显著降低协议调试与回归测试成本。
项目定位与背景
MCP 生态正在快速扩张,服务器实现需要可观测、可复现的调试与测试手段。MCP Inspector 将自己定位为 MCP 服务器的开发者工具,核心目标不是做通用聊天客户端,而是帮助开发者检查服务器行为、定位连接问题,并把测试纳入自动化流程。项目以 @modelcontextprotocol/inspector 单一包发布,提供 Web、CLI、TUI 和实验性 mcpdo 四种入口,GitHub 上超过 1.1 万 stars、1500 多 forks,说明它已成为 MCP 开发者工具箱中的基础设施级项目。当前仓库处于 v2 线,v2/main 活跃开发并定期合并到 main,v1/main 仅接收安全修复,版本策略清晰。
核心功能与技术架构
四种形态各有分工。Web 端是 Vite、React、Mantine 构建的单页应用,配合 Node 后端,适合可视化检查与交互操作;CLI 是面向自动化、CI 和快速 agent 反馈循环的脚本化客户端;TUI 基于 Ink,为习惯终端的开发者提供交互界面;mcpdo 是实验性连接 CLI,连接一次后通过隐式本地守护进程,对命名连接执行多条命令。前三者共用全局 mcp-inspector 二进制,mcpdo 是同一包内的第二个二进制。安装方式统一为 npx 命令,降低尝试门槛。项目还认真处理密钥:OAuth 令牌、OAuth 客户端密钥和 stdio 的 env 值默认存入操作系统钥匙串;在无钥匙串环境回退到 ~/.mcp-inspector/secrets.json,未提供密钥时不会加密,文档对恢复钥匙串、加密文件和仅内存保存都有说明。Node 版本要求为 ^22.23.4、^24.22.1 或 >=26.12.1 的补丁版本,开发时 npm install 会级联到各 client,npm run build 依次构建 web、cli、tui 和 launcher。
创新点与亮点
最大亮点是单包多形态。很多调试工具只覆盖浏览器或命令行,Inspector 让开发者可以在同一套连接与配置体系下切换交互方式:日常用 Web 看细节,CI 用 CLI 跑断言,终端环境用 TUI,长会话用 mcpdo 复用连接。其次是确定性测试导向。CLI 的可脚本化能力使 MCP 服务器测试可以像普通服务一样进入流水线,减少手工复现。mcpdo 的隐式本地守护进程思路也值得关注,它把“连接一次、执行多命令”抽象成命名连接,适合频繁调用同一服务器的场景。密钥管理同样体现了工程成熟度:优先钥匙串,回退策略透明,并明确提示无钥匙串环境的风险。
与同类项目对比
相比通用 MCP 客户端或 IDE 插件,Inspector 更聚焦服务器调试与测试,不追求聊天体验,而是提供检查、脚本和连接管理能力。相比单一 Web 调试器,它多了 CLI 与 TUI,能覆盖 CI 和远程终端;相比开发者自写测试脚本,它内置连接管理、密钥存储和配置拆分,减少重复造轮子。其不足也需客观看待:mcpdo 仍属实验性,稳定性待验证;无钥匙串环境回退文件默认不加密,敏感场景需自行处理;Node 版本要求较严格;v1 到 v2 存在 CLI 参数、--config 与 --catalog 拆分等迁移成本。
上手指南或快速开始
最快方式是直接运行 npx @modelcontextprotocol/inspector 打开 Web UI;加 --cli 使用命令行,加 --tui 进入终端界面;mcpdo 可通过 npx -p @modelcontextprotocol/inspector mcpdo --help 查看用法。参与开发需先确认 Node 版本,在仓库根目录执行 npm install,再执行 npm run build。Web 日常迭代可进入 clients/web 运行 npm run dev 获得 HMR;launcher 脚本运行构建产物,因此先构建再运行。从 v1 升级应阅读迁移指南,重点关注 CLI 标志、配置拆分、Node 引擎升级和不再发布的内容。
总结与展望
MCP Inspector 以多形态、单包和自动化友好为核心,把 MCP 服务器调试从手工操作推进到可脚本、可复现的工作流。它适合作为日常调试入口,也适合作为 CI 中的测试节点。未来若 mcpdo 走向稳定、密钥管理继续增强、v2 文档与迁移体验完善,它有望成为 MCP 服务器质量保障的基础设施。建议团队先用 CLI 建立回归测试,再按场景组合 Web 与 TUI,并在敏感环境中优先配置系统钥匙串或加密回退文件。
项目信息
| 项目名称 | modelcontextprotocol/inspector |
| 编程语言 | TypeScript |
| Star 数 | 11331 |
| Fork 数 | 1581 |
| 主题标签 | cli, debug, mcp, tool, tui, web |