3.3 调试利器——MCP Inspector 实战

小周的 Server 有时能用有时不能用。他需要一个调试工具来搞清楚到底发生了什么。

上一节小周写好了 Client 和 Server，但代码跑不通是常态——学会调试比学会写代码更重要。

MCP Inspector 就是这个工具——它是一个可视化的 MCP 调试器，让你看到每一条消息、每一个工具调用。

---

Inspector 是什么

Inspector 包含两个组件：

组件	说明	默认端口
MCP Inspector Client (MCPI)	React Web UI	6274
MCP Proxy (MCPP)	协议桥接，连接 UI 和 Server	6277

浏览器

(UI)

←→

MCP Proxy

(桥接)

←→

Server

(被调试)

---

启动 Inspector

调试本地 Server

# 调试 Python Server
npx @modelcontextprotocol/inspector python server.py

# 调试 TypeScript Server
npx @modelcontextprotocol/inspector npx tsx server.ts

# 带环境变量
npx @modelcontextprotocol/inspector -e API_KEY=xxx python server.py

调试远程 Server

npx @modelcontextprotocol/inspector --url https://my-server.example.com/mcp

用配置文件

npx @modelcontextprotocol/inspector --config mcp.json --server my-server

启动后，浏览器会自动打开 Inspector UI（http://localhost:6274）。

---

UI 模式功能

Inspector 的 UI 分为几个 Tab，布局大致如下：

MCP Inspector● 已连接

Server Conn

Resources

Tools

Notifications

· 初始化交换的 JSON 消息

· 工具列表 / 参数表单

· 执行结果

· 通知日志

消息历史（可展开查看每条 JSON-RPC 消息）

Inspector 的 UI 分为几个 Tab：

Server Connection

选择传输类型、配置命令/参数/环境变量、连接/断开。能看到完整的初始化交换过程

Resources

浏览资源列表、查看元数据、点击读取内容。能看到 URI、mimeType 等详细信息

Tools

查看工具列表和 Schema、表单输入参数、执行工具并实时查看结果和结构化输出

Notifications

查看 Server 日志、进度通知、所有推送消息。排查「为什么不工作」的关键

---

CLI 模式（自动化）

Inspector 也有命令行模式，适合 CI/CD 和快速验证：

# 列出工具
npx @modelcontextprotocol/inspector --cli python server.py --method tools/list

# 调用工具
npx @modelcontextprotocol/inspector --cli python server.py \
  --method tools/call --tool-name add-todo --tool-arg text="测试"

# 远程 Server
npx @modelcontextprotocol/inspector --cli https://my-server.com/mcp \
  --transport http --method tools/list

场景	UI 模式	CLI 模式
开发调试	交互式探索	快速验证
CI/CD	不适用	自动化测试
工具测试	表单输入、实时结果	命令行、JSON 输出

---

问题诊断流程图

遇到问题时，按这个顺序排查：

Server 不工作？

⏱ 启动失败（连接超时）

检查 command 路径是否为绝对路径

检查 Python / Node 版本是否符合要求

检查依赖是否安装（pip install mcp / npm install）

📭 连接成功但工具列表为空

在 Inspector 中查看初始化交换——capabilities 是否包含 tools？

检查代码中 @mcp.tool() 或 server.tool() 是否正确注册

检查 JSON 配置格式是否正确

❌ 工具出现但调用失败

在 Inspector 的 Tools Tab 中手动执行

查看返回的错误信息

切到 Notifications Tab 查看 Server 日志

检查参数 Schema 是否匹配

⚠️ 调用成功但结果异常

检查 stdout 是否被 print() 污染

确认所有日志写入 stderr

在 Inspector 的 Notifications Tab 查看 Server 原始输出

---

常见问题排查

小周遇到的问题和解决方案：

问题 1：Server 启动失败

症状	可能原因	解决
连接超时	命令路径错误	用绝对路径配置 command
工具不出现	JSON 配置语法错误	检查 mcpServers JSON 格式
环境变量缺失	stdio 进程不继承所有 env	在 env 字段显式传递

问题 2：工具列表为空

在 Inspector 中排查：

1. 打开 Server Connection Tab
2. 查看初始化交换——Server 的 capabilities 是否包含 tools？
3. 如果包含，切到 Tools Tab——工具列表是否显示？
4. 如果为空，检查代码中 @mcp.tool() 或 server.tool() 是否正确注册

问题 3：工具调用失败

在 Inspector 中排查：

1. 在 Tools Tab 中手动执行工具
2. 查看返回的错误信息
3. 切到 Notifications Tab 查看 Server 日志

问题 4：stdout 被污染

这是 stdio Server 最常见的问题。如果 Server 代码中有 print() 调试输出，它会写入 stdout，破坏 JSON-RPC 消息解析。

# ❌ 错误——print 写入 stdout，破坏协议
@mcp.tool()
def my_tool():
    print("调试信息")  # 这会破坏 JSON-RPC！
    return "结果"

# ✅ 正确——用 stderr 或 logging
import sys
@mcp.tool()
def my_tool():
    print("调试信息", file=sys.stderr)  # 写入 stderr，不影响协议
    return "结果"

永远不要在 stdio Server 中用 print() 输出调试信息

所有日志必须写入 stderr（print(..., file=sys.stderr)）或使用 logging 模块。

---

安全提示

• Inspector 启动时自动生成随机 session token
• 默认绑定 localhost，不要在不可信网络设置 HOST=0.0.0.0
• 绝对不要设置 DANGEROUSLY_OMIT_AUTH=true（存在 RCE 风险 CVE-2025-49596）

---

Claude Desktop 调试

如果问题出在 Claude Desktop 而不是 Server：

查看日志：

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

查看 Server 状态：点击聊天输入框 "+" 图标，悬停 "Connectors" 查看已连接的 Server 和工具。

高级调试（Chrome DevTools）：

1. 在 Application Support 目录创建 developer_settings.json：{"allowDevTools": true}
2. 用 Command-Option-I（macOS）或 Ctrl+Alt+I（Windows）打开 DevTools
3. Console 面板查看客户端错误，Network 面板查看消息载荷

---

本节核心要点

• MCP Inspector 是官方的可视化调试工具——UI 模式交互探索，CLI 模式自动化测试
• 四个 Tab：Connection、Resources、Tools、Notifications
• 最常见的问题：stdout 被非协议数据污染——所有日志必须写入 stderr
• 配置变更后必须完全重启客户端
• Claude Desktop 可通过日志文件和 DevTools 调试

练习：用 Inspector 调试你上一节写的 Todo Server。试试在工具代码中加 print() 看看会发生什么，然后改为 print(..., file=sys.stderr)。

---

← 上一节：第一个 MCP Client | 目录 | 下一节：安全与授权 →