一款用于检查 Model Context Protocol (MCP) 服务器的开发者工具。它以单个包 @modelcontextprotocol/inspector 的形式发布,提供四种检查服务器的方式:
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
[!WARNING] 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.23.4 || ^24.22.1 || >=26.12.1:每个受支持系列上的补丁版本。
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 workspace——clients/* 下的每个客户端都保留自己的 package.json 和 node_modules,共享代码位于 core/,通过 @inspector/core 构建时别名使用。core/ 导入的每个运行时依赖都只在仓库根目录的 package.json 中声明一次,每个客户端只声明该客户端单独使用的依赖——其 UI 技术栈、其打包器内联的包、其开发工具——这使得 clients/cli 和 clients/launcher 没有自己的运行时依赖。关于添加依赖(根目录 vs. 客户端、dependencies vs. devDependencies,以及打包器 external 列表)的具体含义,请参见 local-dev skill。
inspector/
├── clients/
│ ├── web/ Web client (Vite + React + Mantine). src/ = browser app; server/ = Node backend
│ ├── cli/ CLI client (tsdown 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, tsdown 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 |
| 从 tsup 迁移到 tsdown | 客户端打包为何迁移到 tsdown、选项映射、不会导致构建失败的陷阱,以及每个客户端迁移的实测结果 |
| 通过 HTTPS 提供 Web UI | INSPECTOR_TLS_KEY_PATH / INSPECTOR_TLS_CERT_PATH、受信任的本地 mkcert 设置、自定义主机名和 ALLOWED_ORIGINS,以及用于出站私有 CA 服务器的 NODE_EXTRA_CA_CERTS |
| Docker | 运行容器镜像——端口、卷,以及在容器中持久化密钥 |
| 密钥存储位置 | 每个运行时如何选择密钥存储——操作系统钥匙串、secrets.json 或内存——以及文件加密、锁定和迁回钥匙串 |
| 从 v1 迁移到 v2 | CLI 标志映射、--config 与 --catalog、Node 引擎版本提升、环境变量重命名 |
| 环境变量 | 每个会改变运行时行为的变量——认证、端口、存储、密钥存储、日志、代理——以及用于自签名服务器的 Node TLS 变量 |
| MCP 服务器配置 | Inspector 连接到哪个(些)服务器,以及配置文件格式 |
| 审查 MCP App | 用于自动化 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 以来贡献实际是如何发生的——端到端的 issue 驱动工作、规则/技能拆分、取代 Dependabot 的清扫、质量门禁,以及它的发展方向 |
每个客户端从自己的文件夹进行自验证;根脚本将它们串联起来。没有聚合的根 test 脚本。