MCP Inspector：测试和调试 MCP 服务器

Mindket 编辑部 · 发布于 2026年11月4日 · 更新于 2026年11月6日 · 阅读约 9 分钟

黑色横幅，标题是“MCP 实战课”，下面一行写着“用 Python 或 TypeScript 写 MCP 服务器，测试并接入”。

MCP Inspector 是官方出的 MCP 服务器测试工具。运行 npx @modelcontextprotocol/inspector，后面跟上你服务器的启动命令，再打开它打印出来的网址。你可以列出并调用工具、查看提示词和资源，还能看到往返的 JSON-RPC 消息。加上 --cli 就能在脚本和 CI 里发单个请求。

本节内容

你会在自己的服务器上启动 Inspector，调用一个工具，并读到这次调用背后的 JSON-RPC 原始消息。
给它用打过补丁的 Node，即使你的服务器是用 Python 写的也一样。
Console 标签页显示 stdio 服务器的 stderr，Network 标签页显示 HTTP 流量，两者不会同时出现。
--cli 模式只发一个请求就退出，适合 shell 脚本和 CI。

全部课程

本页目录

开始之前
一步步操作（附截图）
换成你自己的服务器
标签页一览
用它来找故障
命令行模式
协议时代：legacy、auto 和 modern
把 Inspector 用得安全
David Soria Parra 谈协议时代背后的无状态协议
常见错误
动手试试
下一课：把服务器接到真正的应用里
自测一下
常见问题
资料来源

开始之前

Inspector 是 MCP 服务器的参考开发工具，MCP 的调试指南把它列为出问题时的第一站。一个包 @modelcontextprotocol/inspector 里有三种客户端，共用一个可执行文件：网页界面、命令行客户端和终端界面。它们共用同样的传输方式和配置。

Node.js 22.23.4、24.22.1 或 26.12.1，或者同一系列里更新的版本。Inspector 通过 npx 运行，不用另外安装。
一个待测的服务器。第 1 课和第 2 课的天气服务器都能用，任何已发布的服务器也行。
一个浏览器，用于默认的网页模式。命令行和终端模式不需要。

一步步操作（附截图）

图里用的是已发布的文件系统服务器，指向一个放着示例笔记的文件夹，所以你不用先写服务器就能跟着做。先在一个文件夹里放几个文件，再到另一个文件夹运行 npm install @modelcontextprotocol/server-filesystem，装好这个服务器。你自己的服务器做法一样，把它的启动命令放到图里 node 和路径所在的位置。

用 node --version 检查 Node，输出应是上面列表里的某个版本，或同一系列里更新的版本。然后输入 npx -y @modelcontextprotocol/inspector，后面跟 node、node_modules\@modelcontextprotocol\server-filesystem 下 dist\index.js 的完整路径，以及放文件的那个文件夹。启动器会打印一个带令牌的网址。图里的令牌属于一次已经结束的启动，你的会不一样。
启动器接着会自己在浏览器里打开这个网址。如果没有打开新标签页，就从终端复制这个网址。别凭记忆去敲 localhost:6274，因为每次启动的令牌都不同。在 Servers 页面，拨动你服务器卡片上的开关来连接。卡片名叫 node，下面显示 Inspector 将要运行的命令。由 Inspector 替你启动服务器时，页面上出现 Read-only session（只读会话）提示是正常的。
连上之后，页面显示服务器自己的名字，这里是 secure-filesystem-server。打开 Tools 标签页。列表标题给出工具的数量，这里是 16 个，每个工具在名字上方有一个标题。右侧的 Protocol 栏里，已经记下了取这份列表的 tools/list 请求。
在搜索框里输入 list，选中 List Directory。在 path 一栏填一个服务器允许读取的文件夹，这里就是启动命令里的那个，再选 Execute Tool。
$Tools 标签页里选中了 List Directory。path 一栏填着 C:\tmp\learn-walk-mcp\files，Execute Tool 按钮用金色圈出。$
结果出现在 Results 下面。这个服务器给出的结果是每个文件或文件夹一行，标着 [FILE] 或 [DIR]。
如果右侧一栏里还没打开 Protocol 标签页，就选它。再点 tools/call 卡片右边的上下箭头 Expand，把卡片展开。每次调用是一张卡片，Parameters 是客户端发出的内容，Response 是服务器的回复，两者都是 JSON-RPC。响应里，content 是工具返回的文字，structuredContent 把它又写了一遍。LEGACY 标记显示的是协议时代，下文会讲。
选 Console 标签页。它显示服务器写到 stderr 的内容。这个服务器写出了它可以读取的文件夹，说明客户端没有给它任何根目录，并说它正运行在 stdio 上。服务器启动失败的话，原因会留在这里。

MCP Inspector 2.14.0 在 Windows 上的截图，拍摄于 2026 年 11 月 6 日，服务器是已发布的文件系统服务器。终端那张图是在真实的命令和输出外面画了一个窗口框。那次启动关掉了自动打开浏览器，所以输出里没有 Opening browser... 这一行。

换成你自己的服务器

图里用的是下面代码里 # A built Node server（已构建的 Node 服务器）那条命令，启动的是一个已发布的服务器。你自己的服务器，把它的启动命令放在 Inspector 的名字后面。Inspector 会替你运行那条命令，所以不用单独启动服务器。下面的命令来自各个 SDK 和 Inspector 自己的页面。

# A local TypeScript server (the TypeScript SDK's tutorial)
npx @modelcontextprotocol/inspector npx tsx src/index.ts

# A local Python server, through the mcp command (the Python SDK's README)
uv run mcp dev server.py

# A built Node server
npx @modelcontextprotocol/inspector node path/to/server/index.js

# A published npm server, with an argument
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

# A published PyPI server
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git

# A remote HTTP server
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

用上面的某条命令启动 Inspector，换成你自己服务器的启动命令。然后像图里那样连接服务器并调用一个工具。
故意输入一个错误的参数。工具要是能给出清楚的报错，模型就有机会自己纠正。

标签页一览

看到哪些标签页，取决于服务器在连接时报告了什么。没有提示词的服务器就没有 Prompts 标签页。Apps 标签页需要服务器带有 MCP App 工具，Skills 标签页需要 Skills 扩展，Tasks 标签页需要服务器支持任务。

监控组里有 Tasks、Logs、Protocol、Network 和 Console，连接后它会像图里那样在右侧排成一栏。这样你在 Tools 里操作时，可以同时观察流量。

Inspector 的主要标签页，依据其网页客户端文档
标签页	什么时候显示	用来做什么
Servers	一直显示	添加、编辑、导入和连接服务器，打开每个服务器的设置
Tools	服务器有工具时	把工具的参数结构当表单读，填写、调用，并检查结果
Prompts	服务器有提示词时	填入参数，预览提示词生成的消息
Resources	服务器有资源时	浏览和读取资源，服务器支持时可以订阅
Logs	服务器有日志功能时	读服务器发出的日志通知
Protocol	一直显示	读 JSON-RPC 记录：请求、响应和通知
Network	HTTP 和 SSE 服务器	在 HTTP 层查看状态码、请求头和响应体
Console	stdio 服务器	读服务器进程的 stderr

用它来找故障

失败的调用会先出现在 Protocol 里。它把每个请求和对应的响应配成一对，你能看到客户端发出的参数和服务器返回的错误。被错误码 -32602 拒绝的调用会有单独的面板：工具名不在 tools/list 里时显示 Unknown Tool，其余情况显示 Invalid Parameters。

如果工具在这里能用，到了 Claude Desktop 里却不行，就去比较两边的差别。调试指南说，宿主启动服务器时，工作目录可能没有定义，环境变量也只保留了少数几个，所以指南要求配置里写绝对路径，并设置 env 字段。

按症状决定先看哪里
症状	先看	能看到什么
列表里没有某个工具	Tools，然后是 Protocol	服务器对 `tools/list` 实际返回了什么
调用返回了错误	Protocol	配成一对的请求和错误
stdio 服务器崩溃或什么都不输出	Console	进程的 stderr
HTTP 服务器返回 400 或 401	Network	状态码、请求头和响应体
这里能用，宿主里不行	宿主的配置	启动命令、工作目录和环境变量

命令行模式

每次 --cli 运行都会连接服务器，发送你用 --method 指定的那一个请求，打印结果然后退出。这很适合 CI 流水线、shell 单行命令，以及需要立刻验证服务器改动的编程智能体。--format json 会输出一个不带任何横幅的 JSON 对象，可以直接用管道交给 jq。--tui 则会打开终端界面。

tools/call 返回 isError: true 时，仍会打印它的内容，但这次运行会以 5 退出，所以用 && 串起来的命令会在失败的调用处停下。任何非零退出码，CLI 还会往 stderr 写一行 JSON，说明失败属于哪一类。

# List a server's tools and exit
npx @modelcontextprotocol/inspector --cli node path/to/server/index.js --method tools/list

# Call a tool and pipe the result into jq
npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp --transport http \
  --method tools/call --tool-name get_weather --tool-arg city=Boston --format json | jq .result

值得记住的退出码，依据 CLI 文档
退出码	含义
0	成功
1	用法错误或意外错误
3	服务器要求认证
4	服务器连不上
5	工具出错，或者找不到该工具

协议时代：legacy、auto 和 modern

MCP 的 2026-07-28 修订版改动了协议，所以 Inspector 把“时代”当作每个服务器上的一项设置。可以在 Server Settings 里设置，也可以给命令行或终端界面传 --protocol-era，取值是 legacy、auto 或 modern。

默认值是 legacy，文档也解释了原因：调试工具不能自己去探测，因为 server/discover 探测会让沉默的旧式 stdio 服务器卡住，还会弄乱你想读的记录。对一个新服务器，请检查两遍。MCP 构建指南就是这么做的，并说两次都应该列出同样的工具。

npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/list
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era legacy --method tools/list

每个时代在连接时的做法
时代	Inspector 的做法
`legacy`	默认值。直接发 `initialize`，不做任何探测
`auto`	先探测 `server/discover`，只要结果不是 modern，就退回 `initialize`
`modern`	固定使用 2026-07-28，没有回退，所以不是 modern 的服务器会直接失败

把 Inspector 用得安全

Inspector 的网页后端能在你的电脑上启动进程，所以每个路由都由一个每次启动都不同的令牌守着，而且服务默认只绑定 127.0.0.1。绑定所有网卡会被拒绝，除非设置 DANGEROUSLY_BIND_ALL_INTERFACES=true。DANGEROUSLY_OMIT_AUTH=true 只该用在没有其他人能访问该端口的机器上。

它还会保存机密。OAuth 令牌、OAuth 客户端密钥和 stdio 的 env: 值，有系统钥匙串时就存进钥匙串。没有钥匙串时，它们会落在 ~/.mcp-inspector/secrets.json，除非你提供密钥，否则是不加密的。只把它指向你信得过的命令和服务器，因为它会运行你给的命令。

安全修复来得很勤，时间线里就有好几次，所以启动时用 npx @modelcontextprotocol/inspector@latest，这是 2.14.0 发布说明里给的升级命令。

Inspector v2 的几次发布

2026年7月28日
2.0.0 版
v2 Inspector 成为默认版本，网页、命令行和终端三种客户端放在同一个包里。
来源：MCP Inspector release 2.0.0 (2026年11月5日查阅)
2026年10月7日
2.10.0 版
新增实验性的命令行客户端 mcpdo，多条命令之间保持同一个连接。
来源：MCP Inspector release 2.10.0 (2026年11月5日查阅)
2026年10月21日
2.12.0 版
修复了影响 2.11.0 及之前所有 v2 版本的三个漏洞，其中一个能借 DNS 重绑定拿到 API 令牌。
来源：MCP Inspector release 2.12.0 (2026年11月5日查阅)
2026年10月28日
2.13.0 版
要求大家使用 Node.js 22.23.4、24.22.1 或 26.12.1，或者更新的版本。
来源：MCP Inspector release 2.13.0 (2026年11月5日查阅)
2026年11月4日
2.14.0 版
又修复了三个安全问题，包括 MCP App 沙箱框架内的页面跳转。
来源：MCP Inspector release 2.14.0 (2026年11月5日查阅)

David Soria Parra 谈协议时代背后的无状态协议

David Soria Parra 是 Anthropic 的技术人员，也是 MCP 的联合创建者。他在 2026 年 5 月 22 日在 X 上宣布 2026-07-28 版的候选版发布，概括起来就是：没有握手，没有会话 id，任何请求都能打到任何一个服务器实例上。

协议时代这个设置测的正是这道分界。legacy 用旧的 initialize 握手开场，modern 则固定使用无状态的新版本，不会回退。同一条帖子还把 MCP Apps 和 Tasks 定为一等扩展，它们就是标签页一览里的 Apps 和 Tasks，只有服务器支持时才出现，你做了这类功能就在那里检查。

Inspector 的维护者在 10 月 28 日的 2.13.0 版里加了一条 Node 提醒，距离 Node.js 的安全更新正好一周。这个包仍然接受旧版 Node，所以 npm 不会提醒你。每次开始前运行 node --version，对照本课要求的版本。

没有握手，没有会话 id，任何请求都能打到任何一个服务器实例上

David Soria Parra, Anthropic 技术人员，MCP 联合创建者，引文为译文 · X (2026年11月5日查阅)

David Soria Parra（@dsp_）2026 年 5 月 22 日在 X 上发帖：MCP 2026-07-28 版的候选版发布了。协议现在是无状态的：没有握手，没有会话 id，任何请求都能打到任何一个服务器实例上。另外，扩展成了一等公民（MCP Apps、Tasks），认证得到加固，还有一套正式的弃用政策，免得以后再折腾一遍 — David Soria Parra 在 X 上，2026 年 5 月 22 日

X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日，时间为 UTC。X 用“Show more”截断了帖子后面的内容。点击截图可到 X 上打开原帖。

常见错误

在较旧的 Node 上启动，哪怕你自己的服务器跑在 Node 20 上，或者是用 Python 写的。
凭记忆敲地址，或者沿用旧的标签页。每次启动打印出来的网址里，令牌都是新的。
在 HTTP 服务器上找 Console。Console 是给 stdio 服务器的，HTTP 和 SSE 服务器用 Network。
只测一个时代。默认的 legacy 只走 2025 年版的握手，请再用 modern 检查一遍。
只看最后的结果。Protocol 里的请求显示了真正发出去的参数，参数写错往往先在那里露出来。

动手试试

对第 1 课或第 2 课的天气服务器启动 Inspector，调用工具，再打开 Protocol，找到 tools/call 请求和它的响应。
在命令行里只列出工具名：运行 --cli node build/index.js --method tools/list --format json，用管道交给 jq '.result.tools[].name'，把启动命令换成你自己的。
调用一个不存在的工具名，用 echo $? 查看退出码。CLI 文档里，找不到工具对应的是 5。

下一课：把服务器接到真正的应用里

Inspector 证明了服务器本身能用。第 4 课把它接进 Claude Desktop、Cursor 和 VS Code，并讲清每个应用把配置放在哪里。如果你习惯在终端里工作，给 Claude Code 添加 MCP 服务器讲的是那条路。

自测一下

你要测试的服务器用 node build/index.js 启动，该运行什么？
查看答案
A. npx @modelcontextprotocol/inspector node build/index.js 把服务器自己的启动命令写在 Inspector 的名字后面，Inspector 会替你运行它。
一个 stdio 服务器崩溃了，工具结果里什么也没有，哪个标签页能看到它的 stderr？
查看答案
C. Console Console 显示 stdio 服务器的 stderr，而 Network 是给 HTTP 和 SSE 服务器用的。
哪种模式适合在 CI 里检查服务器的工具列表，然后直接退出？
查看答案
D. 带 --method tools/list 的 --cli --cli 模式会连接服务器，发出你指定的那一个请求，打印结果后退出。
你用默认设置测试了一个新服务器，还应该做什么？
查看答案
B. 再用 --protocol-era modern 检查一遍 默认的 legacy 时代只走较早的握手，所以要再用 modern 检查一遍，并且应该列出相同的工具。

常见问题

怎样对 Python 服务器运行 MCP Inspector？

装好 mcp[cli] 包后运行 uv run mcp dev server.py，或者把启动命令放在 Inspector 的名字后面，比如 PyPI 上的包可以用 uvx mcp-server-git --repository ~/code/mcp/servers.git。Inspector 本身是 Node.js 程序，所以即使服务器是 Python 的，也要装 Node。

怎样用 Inspector 测试远程 MCP 服务器？

用 --server-url 传入地址并指定传输方式，比如 --server-url https://api.example.com/mcp --transport http。服务器要求 OAuth 时，三种客户端都会走完整的流程：它在浏览器里打开授权网址，你登录，它把令牌存在本地磁盘，供以后的运行使用。CI 任务完成不了这个登录，所以在 CI 里请用 --stored-auth-only。

不开浏览器也能用 Inspector 吗？

能。想在脚本里发单个请求就加 --cli，想要交互式的终端界面就加 --tui。两者和网页客户端用同一个核心。

Inspector 用哪个端口？

启动器会打印完整地址，令牌也在里面，文档里的示例用的是 127.0.0.1 上的 6274 端口。请打开打印出来的网址，不要自己敲端口，因为没有令牌的请求会被页面拒绝。

为什么 Inspector 里没有 Console 标签页？

通过 URL 连接的服务器，错误输出留在它自己运行的地方。Inspector 只能读取自己启动的进程的 stderr，所以这类服务器显示的是 Network，而不是 Console。

为什么服务器在 Inspector 里能用，在 Claude Desktop 里却不行？

先查宿主的配置，再查代码。服务器文件写完整路径，宿主找不到 node 或 uv 时，command 也写完整路径，服务器要读的每个变量都放进这一项的 env 字段。然后彻底退出应用，再重新打开。

Inspector 能在 CI 里跑吗？

能。CLI 对每一类失败都有对应的退出码，--stored-auth-only 能让它不再为 OAuth 去打开浏览器。给 tools/list 加上 --strict，工具的结构有错误级别的可移植性问题时它会以 6 退出。

资料来源

MCP docs: MCP Inspector (2026年11月4日查阅)https://modelcontextprotocol.io/docs/tools/inspector
MCP docs: Inspector web client (2026年11月4日查阅)https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/web
MCP docs: Inspector CLI client (2026年11月4日查阅)https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/cli
MCP docs: Inspector protocol eras (2026年11月4日查阅)https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/protocol-eras
MCP docs: Inspector authorization (2026年11月4日查阅)https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/authorization
MCP docs: Debugging (2026年11月4日查阅)https://modelcontextprotocol.io/docs/2026-07-28/tools/debugging
MCP Inspector: README (2026年11月4日查阅)https://github.com/modelcontextprotocol/inspector
MCP TypeScript SDK docs: Build your first server (2026年11月4日查阅)https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/get-started/first-server.md
MCP Python SDK: README (2026年11月4日查阅)https://github.com/modelcontextprotocol/python-sdk
MCP docs: Build an MCP server (2026年11月4日查阅)https://modelcontextprotocol.io/docs/develop/build-server
MCP Inspector release 2.0.0 (2026年11月5日查阅)https://github.com/modelcontextprotocol/inspector/releases/tag/2.0.0
MCP Inspector release 2.10.0 (2026年11月5日查阅)https://github.com/modelcontextprotocol/inspector/releases/tag/2.10.0
MCP Inspector release 2.12.0 (2026年11月5日查阅)https://github.com/modelcontextprotocol/inspector/releases/tag/2.12.0
MCP Inspector release 2.13.0 (2026年11月5日查阅)https://github.com/modelcontextprotocol/inspector/releases/tag/2.13.0
MCP Inspector release 2.14.0 (2026年11月5日查阅)https://github.com/modelcontextprotocol/inspector/releases/tag/2.14.0
David Soria Parra on X: the release candidate for MCP 2026-07-28 (2026年11月5日查阅)https://x.com/dsp_/status/2057780712187580924

找些值得测试的 MCP 服务器

到 Mindket 上浏览 MCP 服务器，再用 Inspector 试试你感兴趣的那些。

浏览 MCP 服务器

本节课的 Markdown 版本 · MCP 实战课：写、测试并接入 MCP 服务器 · 全部课程