MCP Inspector

MCP Inspector

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

• Web — 基于 Vite + React + Mantine 的单页应用，并配有 Node 后端。
• CLI — 可编写脚本的命令行客户端，适用于自动化、CI 和快速 Agent 反馈循环。
• TUI — 使用 Ink 构建的交互式终端 UI。
• mcpdo （实验性） — 连接命令行工具：连接一次，然后通过隐式本地守护进程，对命名连接运行多个命令。详见 clients/mcpdo。

前三种方式通过同一个全局 mcp-inspector 二进制文件运行；mcpdo 是同一软件包中的第二个二进制文件：

npx @modelcontextprotocol/inspector                   # web UI (default)
npx @modelcontextprotocol/inspector --cli             # CLI
npx @modelcontextprotocol/inspector --tui             # TUI
npx -p @modelcontextprotocol/inspector mcpdo --help   # mcpdo

警告

Inspector 会管理密钥——OAuth 令牌、OAuth 客户端密钥和 stdio env: 值——并默认将其存储在操作系统钥匙串中（如果可用）。 如果机器没有钥匙串——例如未安装 libsecret 或 Secret Service 的 Linux、无头和 SSH 会话、Termux，以及挂载了卷的容器——这些密钥会改为保存到 ~/.mcp-inspector/secrets.json，除非你提供密钥，否则不会加密。有关如何恢复钥匙串、加密文件或仅将密钥保留在内存中的说明，请参阅密钥存储位置。

从 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。

快速开始（开发）

需要 Node >=22.19.0。

npm install          # at the repo root; postinstall cascades into every client
npm run build        # web → cli → tui → launcher

日常进行 Web 开发时，直接运行 Vite——HMR 速度快，也无需构建启动器：

cd clients/web && npm run dev

由启动器驱动的脚本运行的是已构建的启动器，因此请先构建：

npm run web        # prod web launcher against clients/web/dist
npm run web:dev    # web launcher in --dev mode (Vite)

v2 不是 npm 工作区——clients/* 下的每个客户端都有自己的 package.json 和 node_modules，共享代码位于 core/，并通过 @inspector/core 构建时别名使用。core/ 导入的每个运行时依赖都只在仓库根目录的 package.json 中声明一次，每个客户端只声明该客户端独自使用的内容——其 UI 技术栈、打包器内联的软件包和开发工具——因此 clients/cli 和 clients/launcher 本身没有运行时依赖。有关添加依赖的说明（根目录还是客户端、dependencies 还是 devDependencies，以及打包器的 external 列表），请参阅 local-dev 技能指南。

项目布局

inspector/
├── clients/
│   ├── web/          Web client (Vite + React + Mantine). src/ = browser app; server/ = Node backend
│   ├── cli/          CLI client (tsup bundle, @inspector/core alias)
│   ├── mcpdo/   Experimental connection CLI (`mcpdo` bin) — bundled into the
│   │                 published package; see clients/mcpdo/README.md
│   ├── tui/          TUI client (Ink + React, tsup bundle)
│   └── launcher/     Shared launcher — provides the `mcp-inspector` bin, dispatches to web/cli/tui
├── core/             Shared code consumed via the `@inspector/core` alias (no package.json)
├── test-servers/     Composable MCP test servers + fixtures used by integration and smoke tests
├── scripts/          Root build/verify tooling (install cascade, smokes, the verify:* guards),
│                     repo automation run from CI (the dependency, Dependabot-alert and SDK sweeps),
│                     maintainer-workflow helpers (the pr:*, board:*, advisory:*,
│                     release:notes, release:tag and action:resolve-pin aliases)
│                     and the Docker image's HEALTHCHECK probe
├── docs/             Task-oriented guides — see below
├── specification/    Design/build specifications
├── skills/           End-user agent skills (e.g. skills/mcpdo teaches an agent to
│                     drive the `mcpdo` CLI) — distinct from .claude/skills/,
│                     which holds this repo's own procedures
├── .claude/skills/   Agent skills: the repo's procedures, invokable by name
├── AGENTS.md         Contribution rules for agents AND humans
└── README.md         You are here

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

文档

指南	涵盖内容
架构	@inspector/core 共享包，以及 Web 客户端的“哑组件” + Storybook 方案
测试与质量门禁	每个 validate / coverage / smoke / verify:* 脚本涵盖的内容、GitHub-CI 与本地门禁的划分，以及支持的浏览器
编写技能	如何编写能实际触发的技能描述，以及用于衡量技能的评估用例——有效的用例结构和调优流程
测试服务	可组合的测试服务和涵盖每项功能的展示配置——要运行什么、要点击什么，以及损坏的构建中发生了什么
发布	tarball 中包含的内容、打包不变量，以及 pack:verify
通过 HTTPS 提供 Web UI	INSPECTOR_TLS_KEY_PATH / INSPECTOR_TLS_CERT_PATH、受信任的本地 mkcert 配置、自定义主机名和 ALLOWED_ORIGINS，以及用于连接出站私有 CA 服务的 NODE_EXTRA_CA_CERTS
Docker	运行容器镜像——端口、卷，以及如何在容器中持久保存密钥
密钥的存储位置	每种运行时如何选择密钥存储——OS 钥匙串、secrets.json 或内存——以及文件加密、锁定和迁回钥匙串
从 v1 迁移到 v2	CLI 标志映射、--config 与 --catalog 的区别、Node 引擎版本升级，以及环境变量重命名
环境变量	所有会改变运行时行为的变量——身份验证、端口、存储、密钥存储、日志记录、代理——以及用于自签名服务的 Node TLS 变量
MCP 服务配置	Inspector 连接的服务，以及配置文件格式
评审 MCP 应用	用于自动化评审 App 工具的 CLI 优先 → 单次 Web 工作流程
对 MCP 服务进行冒烟测试	用于 shell 或 CI 作业的连接 → 列出 → 调用 → 断言工作流程：--format json + jq、退出代码映射，以及如何保持 OAuth 非交互式
追溯补签 DCO	在未运行 DCO 检查期间合并但没有 Signed-off-by: 的十个提交，以及各作者对这些提交的签署认证
启动器与配置整合	为什么启动器会在进程内运行客户端，而不是生成子进程
路线图，2026 年 8 月 → 2027 年 2 月	六个月计划：与已发布的 MCP 路线图保持一致的规范遵循工作、官方扩展支持，以及我们选择开展的体验改进工作
MCP Inspector：我们的 AI 软件工厂	自 v2.0.0 以来贡献如何实际进行——端到端的议题驱动工作、规则与技能的划分、取代 Dependabot 的扫描、质量门禁，以及未来方向

测试与质量门禁

每个客户端都会在自己的文件夹中进行自我验证；根目录脚本会串联这些验证。根目录没有聚合的 test 脚本。

npm run validate     # fast inner loop: format:check + lint + typecheck + build + unit tests
npm run coverage     # the per-file ≥90% gate (lines/statements/functions/branches)
npm run local:gate   # MANDATORY before pushing — every GitHub CI check, plus one local-only one

npm run local:gate 会串联下面的所有检查，以及冒烟测试和 Storybook 测试。测试与质量门禁 负责说明各阶段的列表、每个阶段涵盖的内容，以及其中一项为何仅在本地运行；AGENTS.md 则包含测试规则。

贡献 — AGENTS.md、CLAUDE.md 和技能

AGENTS.md 是修改此代码库的约定，对人类和 AI Agent 同样适用。 它并非只供 Agent 使用的模板，而是包含项目的实际规则：版本和标签规范、TypeScript 与 Mantine/React 标准、测试和覆盖率要求，以及强制性的推送前检查。在进行更改前请先阅读；如果调整了结构、工具或规则，也请及时更新。

代码库中的流程——包含命令和实时 ID 的多步骤操作指南——则放在 .claude/skills/ 中，每个流程对应一个目录，以便仅在任务需要时加载。它们是普通的已提交 Markdown 文件：不理解技能的 Agent 也可以阅读，而 AGENTS.md 则列出了现有内容的索引。Claude Code 用户可以按名称调用它们（/release、/issue-triage，……）。

CLAUDE.md 是 Claude Code 自动加载的入口点；它包含 AGENTS.md，因此 Agent 和人类遵循的是同一事实来源。如果你使用的其他 Agent 会读取 AGENTS.md，也会遵循相同规则。

这里值得强调的一条关键规则是：所有工作都必须由 issue 驱动。 开始前，请在 v2 项目看板上查找或创建跟踪 issue；向 v2/main 提交 PR，并附上 Closes #<issue>。外部贡献只接受 issue，不接受拉取请求——详见 CONTRIBUTING.md。

许可证

请参阅 LICENSE。MCP 项目正在从 MIT License 迁移至 Apache-2.0：新的代码贡献根据 Apache-2.0 授权，文档（不包括规范）根据 CC-BY-4.0 授权；作者最初根据 MIT 授权且未同意重新授权的贡献仍受 MIT 许可约束。该文件包含完整的 Apache-2.0 和 MIT 许可文本，并链接至 CC-BY-4.0 法律文本。