ghcr.io/modelcontextprotocol/inspector:2.5.0

MCP Inspector

用于检查模型上下文协议（MCP）服务器的开发工具。它以单个包 @modelcontextprotocol/inspector 形式提供，支持三种服务器检查方式：

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

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

mcp-inspector

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

[!NOTE] 从 v1 升级？请阅读 v1 → v2 迁移指南 — 包含 CLI 标志、新的 --config 与 --catalog 拆分、Node 引擎版本提升以及不再提供的功能。

[!NOTE] 仓库状态。这是 Inspector 的 v2 版本系列。活跃开发在 v2/main 分支（开发分支 — 所有 v2 PR 均以此为目标）进行，里程碑版本时会合并到 main 分支；main 是默认分支，包含最新发布的 v2 版本，发布到 npm 的 latest 标签。旧版 v1 系列位于 v1/main 分支 — 仅修复安全问题，直接从该分支发布到 npm 的 v1-latest 标签（npx @modelcontextprotocol/inspector@v1-latest）。分支/看板约定详见 AGENTS.md。

快速开始（开发）

需要 Node >=22.19.0。

npm install # 在仓库根目录执行；postinstall 会级联安装所有客户端依赖
npm run build # 构建顺序：web → cli → tui → launcher

对于日常 Web 迭代，可直接运行 Vite —— 支持快速 HMR，无需构建启动器：

cd clients/web && npm run dev

启动器驱动的脚本会运行已构建的启动器，因此需先执行构建：

npm run web # 生产环境 Web 启动器，基于 clients/web/dist
npm run web:dev # Web 启动器（--dev 模式，使用 Vite）

v2 不是 npm workspace —— clients/* 下的每个客户端都有自己的 package.json 和 node_modules，共享代码存放在 core/ 中，通过构建时别名 @inspector/core 引入。core/ 导入的所有运行时依赖均在仓库根目录的 package.json 中统一声明，每个客户端仅声明其单独使用的依赖 —— 包括 UI 框架、打包器内联包、开发工具等 —— 这使得 clients/cli 和 clients/launcher 自身没有运行时依赖。关于添加依赖的具体规则（根目录 vs 客户端、dependencies vs devDependencies 以及打包器 external 列表），详见 local-dev 技能。

项目布局

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）
├── test-servers/ 可组合的 MCP 测试服务器 + 集成测试和冒烟测试使用的 fixtures
├── scripts/ 根目录构建/验证工具（级联安装、冒烟测试、verify:* 检查）
├── docs/ 任务导向指南 —— 见下文
├── specification/ 设计/构建规范
├── .claude/skills/ 代理技能：仓库流程，可通过名称调用
├── AGENTS.md 代理和人类的贡献规则
└── README.md 本文档

每个客户端都有自己的 README，包含客户端特定细节： web · cli · tui · launcher。

npm run local:gate 会串联以下所有检查，以及冒烟测试和 Storybook 测试。测试与质量门禁 包含阶段列表，并说明每个阶段的覆盖范围以及为何其中两个阶段仅限本地；AGENTS.md 本身包含测试规则。

贡献指南 — AGENTS.md、CLAUDE.md 与技能

AGENTS.md 是修改此代码库的契约，对人类和 AI 智能体同样适用。 它并非仅针对智能体的模板文件——它包含项目的实际规则：版本/标签约定、TypeScript 和 Mantine/React 标准、测试与覆盖率要求，以及强制的预推送门禁。修改前请阅读此文件，并且在更改结构、工具或规则时保持其更新。

仓库的流程——包含命令和实时 ID 的多步骤操作指南——存储在 .claude/skills/ 目录中，每个流程对应一个子目录，因此仅在任务需要时才会加载它们。它们是常规提交的 Markdown 文件：不理解技能的智能体也可以阅读它们，并且 AGENTS.md 包含现有技能的索引。Claude Code 用户通过名称调用它们（/release、/issue-triage 等）。

CLAUDE.md 是 Claude Code 自动加载的入口文件；它包含 AGENTS.md，因此智能体和人类使用相同的事实来源。如果使用读取 AGENTS.md 的其他智能体，你将获得相同的规则。

此处值得强调的关键规则：所有工作均由议题驱动。 开始前，请在 v2 项目看板上查找或创建跟踪议题；针对 v2/main 分支提交 PR，并在描述中包含 Closes # 。外部贡献仅接受议题形式，不接受拉取请求——详见 CONTRIBUTING.md。

许可证

MIT。