MCP Inspector

一个用于检查 Model Context Protocol（MCP）服务器的开发者工具。它以单个包 @modelcontextprotocol/inspector 的形式发布，提供三种检查服务器的方式：

• Web — 一个基于 Vite + React + Mantine 的单页应用，带有 Node 后端。
• CLI — 一个可脚本化的命令行客户端，用于自动化、CI 和快速的代理反馈循环。
• TUI — 一个使用 Ink 构建的交互式终端 UI。

这三种方式都通过一个全局的 mcp-inspector 二进制文件运行：

npx @modelcontextprotocol/inspector          # web UI（默认）
npx @modelcontextprotocol/inspector --cli    # CLI
npx @modelcontextprotocol/inspector --tui    # TUI

从 v1 升级？ 请阅读 v1 → v2 迁移指南 — CLI 标志变更、新的 --config 与 --catalog 分离、Node 引擎版本提升，以及不再随附的包。

仓库状态。 这是 Inspector 的 v2 系列。活跃开发在 v2/main（开发分支 — 所有 v2 PR 都针对它）上进行，并在里程碑版本时合并到 main；main 是默认分支，包含最新发布的 v2，发布到 npm 的 latest 标签。遗留的 v1 系列位于 v1/main — 仅安全修复，直接从该分支发布到 npm 的 v1-latest 标签 (npx @modelcontextprotocol/inspector@v1-latest)。有关分支/看板约定，请参阅 AGENTS.md。

项目布局

v2 不是 npm 工作区。每个客户端在 clients/* 下维护自己的 package.json 和 node_modules；共享代码位于 core/，并通过构建时别名 @inspector/core 使用（没有自己的 package.json）。在根目录执行一次 npm install 会级联安装到每个客户端（参见 Setup）。

inspector/
├── clients/
│   ├── web/          # Web 客户端（Vite + React + Mantine）。src/ = 浏览器应用；server/ = Node 开发/生产后端
│   ├── cli/          # CLI 客户端（tsup 打包，@inspector/core 别名）
│   ├── tui/          # TUI 客户端（Ink + React，tsup 打包）
│   └── launcher/     # 共享启动器 — 提供 `mcp-inspector` 二进制文件，分派到 web/cli/tui
├── core/             # 通过 `@inspector/core` 别名使用的共享代码（无 package.json）
│   ├── auth/         # OAuth：提供者、发现、存储、会话中恢复（浏览器/Node/远程后端）
│   ├── client/       # 安装级客户端配置 (`client.json`)：浏览器安全的解析/验证 + Node 加载/保存，远程后端，密钥
│   ├── json/         # JSON 和参数/参数转换工具
│   ├── logging/      # 静默的 pino 日志单例
│   ├── mcp/          # InspectorClient 运行时、状态存储、传输、配置导入
│   ├── node/         # 仅 Node 的共享助手：版本读取器、hostUrl（主机规范化/标准化 + 全接口/回环检测）
│   ├── react/        # 基于状态存储的 React hooks
│   └── storage/      # OAuth 持久化后端的文件 I/O 助手
├── test-servers/     # 用于集成测试的可组合 MCP 测试服务器和夹具
├── scripts/          # 根构建/验证工具（安装级联、冒烟测试、验证构建门槛、验证格式覆盖率、验证依赖锁步、打包验证）
├── docs/             # 任务导向指南（v1→v2 迁移、服务器配置、MCP App 审查、启动器/配置计划）
├── specification/    # 设计/构建规范
├── AGENTS.md         # 面向代理和人类的贡献规则（见下文）
└── README.md         # 你在这里

每个客户端都有自己包含详细信息的 README：
web · cli · tui · launcher。

任务导向指南位于 docs/ 下：

• 从 v1 迁移到 v2 — v1 → v2 映射：CLI 标志映射、--config 与 --catalog 语义及前后示例、Node 引擎版本提升（>=22.7.5 → >=22.19.0）、环境变量重命名以及不再随附的子包。
• MCP 服务器配置 — Inspector 连接哪个（些）服务器：--catalog 与 --config、临时目标、-- 分隔符、文件格式及其 Inspector 特定的 per-server 字段。所有三个客户端共享；cli 和 tui 的 README 将其服务器选项部分委托给它。
• 审查 MCP 应用 — CLI 优先 → 一次性 Web 的自动化 App 工具审查方案：--app-info 探测 → 深度链接导航 → 渲染小部件，以及 OAuth 交接和代理支持。
• 启动器和配置整合 — 为什么启动器在进程内运行客户端而不是生成子进程，以及共享配置处理器如何配合。

安装

需要 Node >=22.19.0。

npm install     # 根目录安装；postinstall 级联到每个客户端

• 全新克隆： 在仓库根目录运行 npm install。
• 拉取更改了客户端依赖的代码后： 在根目录重新运行 npm install 以重新同步所有客户端。

级联 (scripts/install-clients.mjs) 仅用于开发 — 当包作为依赖安装时它会提前退出，并且发布的 tarball 只包含每个客户端的 build/，因此最终用户不受影响。设置 INSPECTOR_SKIP_CLIENT_INSTALL=1 可跳过它。

开发期间运行

对于日常 Web 迭代，直接从 web 客户端运行 Vite（快速 HMR，无需构建启动器）：

cd clients/web && npm run dev

下面由启动器驱动的脚本运行已构建的启动器，因此需要先构建 (npm run build)：

npm run web        # 针对 clients/web/dist 的生产环境 Web 启动器
npm run web:dev    # 以 --dev 模式运行的 Web 启动器（Vite）