用 MCP Inspector 调试服务器

这篇适合谁、读完能做到什么

你写好了一个 MCP 服务器，还没有 AI 应用可以接它，或者接了但工具表现不对，想先单独把服务器本身测清楚。读完这篇，你应该能用 MCP Inspector 连上服务器，逐个测试工具、资源和提示词，读懂消息日志，并按步骤排查连接失败和工具不出现这类常见问题。^[1]

先看协议版本

提醒，带 --sse 的命令和以 /sse 结尾的地址测试的是旧的 HTTP+SSE 传输。如果服务器遵循的是 MCP 2026-07-28，要换用支持 Streamable HTTP 的 Inspector 版本，并在界面里选择这种传输。^[1]

Inspector 是什么

MCP Inspector 是一个调试工具，不需要完整的 AI 宿主应用，就能交互式地测试和排查 MCP 服务器。它提供图形界面，可以发送请求、查看响应，并看清服务器的行为。列出的几类问题，它都能回答：服务器有没有在运行，工具有没有注册正确，响应是什么格式，以及某个工具为什么不工作。^[1]

准备和安装

需要 Node.js 18 或更新版本，npm 随 Node.js 一起安装，另外还要有一个待测试的 MCP 服务器。^[1]

安装有三种方式。想快速试一下，直接用 npx @modelcontextprotocol/inspector，推荐这样做。想全局安装，就执行 npm install -g @modelcontextprotocol/inspector，然后运行 mcp-inspector。想让项目自己带着它，可以在项目里执行 npm install --save-dev @modelcontextprotocol/inspector，再在 package.json 的 scripts 里加一项 "inspector": "mcp-inspector"。^[1]

连接服务器

stdio 服务器是以本地进程运行、通过标准输入输出通信的服务器。给出的命令如下，分别对应 Python、Node.js，以及带环境变量的写法：

# Python server
npx @modelcontextprotocol/inspector python -m your_server_module

# Node.js server
npx @modelcontextprotocol/inspector node ./build/index.js

# With environment variables
OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.py

如果服务器以 HTTP 服务的形式运行，先启动服务器，再让 Inspector 通过 --sse 连接。例子是服务器运行在 http://localhost:8080：

python server.py  # Server running on http://localhost:8080
npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse

Inspector 的网页界面通常在 http://localhost:5173 打开。^[1]

测试工具

点击 Tools 标签，Inspector 会自动调用 tools/list，列出每个工具的名称、描述和输入结构（schema）。选中一个工具，在表单里填好参数，点击 Run Tool，结果会显示在结果面板里。^[1]

用一个名为 add 的计算器工具做例子：a 填 25，b 填 17，返回的文本是 42。返回的结构大致如下：

{
  "content": [
    {
      "type": "text",
      "text": "42"
    }
  ]
}

工具出错时，Inspector 会显示错误响应。例子是错误码 -32602，消息为 "Invalid params: 'b' is required"，也就是缺少参数 b：

{
  "error": {
    "code": -32602,
    "message": "Invalid params: 'b' is required"
  }
}

列出的常见错误码有：-32700 是解析错误，即 JSON 无效；-32600 是无效请求；-32601 是找不到方法；-32602 是参数无效；-32603 是内部错误。^[1]

测试资源和提示词

Resources 标签会调用 resources/list，显示每个资源的 URI、名称、描述和 MIME 类型。选中资源后点击 Read Resource，就能看到返回的内容。例子是 file:///config/settings.json，内容类型为 application/json。^[1]

Prompts 标签会调用 prompts/list。选中一个提示词，填好需要的参数，点击 Get Prompt，就能看到渲染后的提示消息。^[1]

资源和提示词的测试与工具相同：先看列表是否完整，再逐个读取或获取内容，确认返回的结构和预期一致。^[1]

看懂消息日志

消息日志记录了所有 MCP 协议消息。示例来自旧的 2025-11-25 服务器，里面包含已被去掉的 initialize 握手：

14:32:01 → {"jsonrpc":"2.0","id":1,"method":"initialize",...}
14:32:01 ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",...}}
14:32:02 → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
14:32:02 ← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
14:32:05 → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
14:32:05 ← {"jsonrpc":"2.0","id":3,"result":{"content":[...]}}

2026-07-28 的服务器改用每个请求自带的元数据，并用 server/discover 代替握手。读日志时可以按四点看：每个请求（→）都应该有对应的响应（←）；响应里出现 "error" 要注意；时间上的大段空白可能说明性能问题；还要确认服务器和客户端使用的协议版本一致。^[1]

常见排查场景

服务器连不上。 Inspector 显示 "Disconnected"，或一直停在 "Connecting..."。检查清单是：启动命令是否正确；依赖是否都装好；服务器路径是绝对路径还是相对于当前目录；需要的环境变量是否设置。^[1]

排查时，可以先在终端里单独测试服务器，检查是否有导入错误，确认 MCP SDK 已经安装：

# Test server manually first
python -c "import your_server_module; print('OK')"

# Check for import errors
python -m your_server_module 2>&1 | head -20

# Verify MCP SDK is installed
pip show mcp

工具列表是空的。 列出三种可能：初始化时没有注册工具；服务器启动后崩溃了；tools/list 的处理函数返回了空数组。对应的做法是在消息日志里查看 tools/list 的响应，在工具注册的代码里加日志，并在 Python 中确认 @mcp.tool() 装饰器存在。^[1]

工具返回错误。 先仔细读错误消息，检查参数类型是否与 schema 一致，在工具里加上带详细信息的异常处理，并查看服务器日志中的堆栈信息。^[1]

资源内容为空。 检查文件路径或 URI 是否正确，服务器是否有读取权限，以及内容是否被正确返回。^[1]

进阶用法

对需要认证的 SSE 服务器，可以在命令里加上 --header，例如 --header "Authorization: Bearer your-token"。要看更详细的日志，可以在命令前加 DEBUG=mcp*，例如 DEBUG=mcp* npx @modelcontextprotocol/inspector python server.py。^[1]

消息面板里的 Export Log 按钮可以把消息日志导出为 JSON 文件，方便留存或发给同事一起排查。^[1]

在 VS Code 里运行

给了两种方式。一种是在 .vscode/launch.json 里加一个配置，runtimeExecutable 为 npx，runtimeArgs 里依次包含 @modelcontextprotocol/inspector、python 和 ${workspaceFolder}/server.py。另一种是在 .vscode/tasks.json 里加一个名为 "Start MCP Inspector" 的后台任务，运行 Node.js 服务器的构建产物。这样一来，调试启动时 Inspector 会随之运行，不必每次手敲命令。^[1]