MCP Inspector 实用指南：如何测试和调试 MCP Server

MCP Inspector 是官方提供的 Model Context Protocol 服务器测试与调试工具。运行 npx @modelcontextprotocol/inspector 就会打开一个浏览器界面，你可以连接任意 stdio 或 Streamable HTTP 服务器，调用它的工具、读取资源、渲染提示词，并实时查看原始 JSON-RPC 流量。同一个包还提供了可脚本化的 CLI（--cli，适合 CI）和终端界面（--tui）。

本文基于 Inspector 当前的 v2 版本线（撰写时为 2.11）。如果你看的旧教程提到 6277 端口上的代理或 MCP_PROXY_AUTH_TOKEN，那讲的是 v1——下文会标出两者的区别。

MCP Inspector 是什么（以及 v2 改了什么）

Inspector 是一个面向人类开发者的参考 MCP 客户端。与其把服务器接进 Claude、Cursor 或其他宿主，再去猜某个工具为什么没出现，不如直接用 Inspector 连上去，准确看到服务器声明了什么、返回了什么。

根据官方文档，现在一个包、一个可执行文件里包含三种客户端：

根据迁移指南，v2 的主要变化：

• 需要 Node 22.19.0 或更高版本。 旧版 Node 可能能装上，但之后会以难以理解的方式出错——先检查 node -v。
• 代理没了。 v1 在 6274 跑界面、在 6277 跑代理。v2 只在 6274 跑一个 Web 服务器（另加一个用于 MCP Apps 的 6275 沙箱端口）。
• 服务器列表存放在 catalog 文件中，路径为 ~/.mcp-inspector/mcp.json，由 Web、CLI、TUI 共享，不再存在浏览器 localStorage 里。
• 认证 token 改名为 MCP_INSPECTOR_API_TOKEN（旧名仍可作为后备使用）。
• 还需要 v1？ 用 npx @modelcontextprotocol/inspector@v1-latest 固定版本。

运行 Inspector

无需安装。在 Node 22.19+ 环境下：

# 不带服务器打开 Web 界面，在 Servers 标签页中添加服务器
npx @modelcontextprotocol/inspector

# 打开 Web 界面并直接连接本地 stdio 服务器
npx @modelcontextprotocol/inspector node build/index.js

命令会打印一个包含本次启动会话 token 的 URL，并在浏览器中打开。请使用打印出来的这个 URL，不要手动输入 localhost:6274——后端可以在你的机器上启动进程，因此每个 API 调用都受这个 token 保护。如果不希望自动打开浏览器标签页，设置 MCP_AUTO_OPEN_ENABLED=false。

首次启动时，Web 客户端会在 catalog 中预置三个示例服务器（一个限定在 /tmp 的文件系统服务器、"everything" 参考服务器，以及一个托管的示例服务器），你可以先点点看，再接入自己的服务器。

连接 stdio 服务器

对于本地服务器，把启动它的命令作为位置参数传入。Inspector 自身参数之后的内容就是服务器命令：

# 你正在开发的服务器
npx @modelcontextprotocol/inspector node build/index.js

# 已发布的 npm 服务器
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

# 通过 uvx 运行已发布的 Python 服务器
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/my-repo

# 环境变量与服务器参数
npx @modelcontextprotocol/inspector -e API_KEY=xxx -- node build/index.js --verbose

用 -e KEY=value 传环境变量，用 --cwd <path> 设置服务器的工作目录。在 Web 和 TUI 客户端中，-- 之后的所有内容都会传给服务器命令。Filesystem 服务器很适合作为第一个测试目标，因为它会用到 tools、resources 和 roots 能力。

连接 Streamable HTTP（远程）服务器

对于远程服务器，直接传 URL。Inspector 只根据路径后缀推断传输方式：

# 路径以 /mcp 结尾，推断为 Streamable HTTP
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

# 其他路径必须加 --transport
npx @modelcontextprotocol/inspector --cli https://api.example.com/v1 --transport http --method tools/list

# 静态 API key 或 bearer 请求头
npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN" --method tools/list

注意，结尾带斜杠（/mcp/）也会被视为无法判断。v1 在这种情况下会悄悄回退到 SSE；v2 则拒绝猜测。你也可以在 Web 界面的 Servers 标签页添加服务器，并在它的 Server Settings 里设置请求头、超时和 OAuth。

在 Web 界面中测试 Tools、Resources 和 Prompts

连接后，标签栏只会显示服务器能力所支持的内容：

一个实用的测试流程：

1. 打开 Tools，选一个工具，分别尝试一次正确调用和一次故意出错的调用（缺少必填字段、类型错误）。好的服务器会返回清晰的工具错误，让模型能够自我修正。
2. 点击时盯着 Protocol。把监控组固定（pin）后，它会作为右侧边栏停在 Tools 旁边。
3. 当出现静默失败时，查看 Console（stdio）或 Network（HTTP）——堆栈信息和 401 都会出现在那里。
4. 在 Resources 中确认 MIME 类型以及模板能正确解析。如果不确定某样东西该做成 resource 还是 tool，参见 MCP resources 与 tools 的区别。

Tools 标签页还会标记 schema 可移植性问题——技术上合法、但会被某些真实客户端拒绝的 JSON Schema。发布服务器前值得检查一下。

每个服务器的 Server Settings 可以设置 roots、请求头、超时、OAuth 字段，以及用于测试分页的 "Fetch Lists One Page at a Time" 开关——如果你的服务器暴露了大量工具，这会很有用（参见 MCP 工具发现）。

脚本化：用于 CI 和 Agent 的 CLI 模式

CLI 模式会连接、执行一个 --method、打印结果后退出。模式参数必须放在最前面：

# 列出工具
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# 用 key=value 参数调用工具
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name mytool --tool-arg key=value --tool-arg count=3

# 以单个 JSON 对象传参（不做类型转换）
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name mytool --tool-args-json '{"id":"012"}'

# 资源与提示词
npx @modelcontextprotocol/inspector --cli node build/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node build/index.js --method prompts/list

# 机器可读输出，配合 jq
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list --format json | jq '.result.tools[].name'

支持的方法包括 initialize、tools/list、tools/call、resources/list、resources/read、resources/templates/list、prompts/list 和 prompts/get。如果要从一个不是你写的配置文件（例如某个客户端的 mcp.json）中选取服务器，使用只读的 --config 参数配合 --server：

npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server myserver --method tools/list

CLI 有稳定的退出码，很适合做 CI 冒烟测试：

失败时它会向 stderr 写入一行 JSON 错误信息。注意与 v1 的区别：以前工具调用失败也会以 0 退出；v2 会以 5 退出，所以之前"悄悄通过"的 CI 流水线可能开始失败——这才是正确的行为。

认证与 OAuth

对于使用 MCP 授权的服务器，Inspector 会帮你完成 OAuth 流程：

• Web 界面：在 Server Settings 中配置 OAuth（client ID/secret、scopes、refresh token）。需要注册的 Redirect URI 会显示在那里，默认是 http://localhost:6274/oauth/callback。
• CLI 和 TUI：遇到 401 时，CLI 会在 http://127.0.0.1:6276/oauth/callback 启动本地回调，打印授权 URL、打开浏览器，并在你登录后重试。可用 --callback-url 覆盖。
• CI：使用 --stored-auth-only，这样运行时永远不会等待浏览器，而是以 auth_required（退出码 3）快速失败。
• 静态密钥：直接传 --header "Authorization: Bearer ..."。

在可用时，token 会存储在操作系统钥匙串中。在没有钥匙串的机器上（无头 Linux、容器），会回退到 ~/.mcp-inspector/secrets.json，而这个文件除非你提供密钥，否则是未加密的——在共享机器上要注意这一点，也建议阅读我们的 MCP 安全最佳实践。

常见错误与解决方法

Docker 方面，官方镜像为 ghcr.io/modelcontextprotocol/inspector:latest，请只在回环地址上发布端口：docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector:latest。

什么时候用 Inspector，什么时候用真实客户端

用 Inspector 回答"我的服务器是否正确？"——schema、结果、错误、认证、分页。然后换到真实宿主回答"模型能不能用好它？"——工具描述、命名和上下文开销。我们的 Claude Code、Codex 和 ChatGPT 配置指南覆盖了第二步。如果某个工具在 Inspector 中正常、在客户端里却不行，差异几乎总是在客户端一侧：配置、认证，或客户端处理 schema 的方式。

下一步

• 从 MCP.so 目录中挑一个服务器，用 Inspector 连上试试——GitHub MCP Server、Playwright MCP 或 Context7 都是文档完善的好目标。
• 在你的服务器 CI 中加入一个 CLI 冒烟测试（--method tools/list --format json）。
• 正在构建工具很多或会变化的服务器？接下来读 MCP 工具发现。