【工具】使用 MCP Inspector 调试服务的完全指南

Model Context Protocol (MCP) Inspector 是一个交互式开发工具，专为测试和调试 MCP 服务器而设计。本文将详细介绍如何使用 Inspector 工具有效地调试和测试 MCP 服务。

1. MCP Inspector 简介

MCP Inspector 提供了直观的界面，让开发者能够：

• 检查服务器端点和功能
• 测试 Prompts、Resources 和 Tools
• 监控服务器日志和通知
• 验证服务器连接和功能

2. 安装与基本使用

MCP Inspector 可以通过 npx 直接运行，无需额外安装：

# 基本语法
npx @modelcontextprotocol/inspector <命令>

# 带参数的语法
npx @modelcontextprotocol/inspector <命令> <参数1> <参数2>

初次运行时，系统会提示安装必要的包：

Need to install the following packages:
@modelcontextprotocol/inspector@0.10.2
Ok to proceed? (y) y

3. 调试不同类型的 MCP 服务

3.1 调试 NPM 包中的 MCP 服务

# 通用格式
npx -y @modelcontextprotocol/inspector npx <包名> <参数>

# 实例：调试 server-filesystem 服务
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /Users/eulerblind/cursor

3.2 调试 PyPi 包中的 MCP 服务

# 通用格式
npx @modelcontextprotocol/inspector uvx <包名> <参数>

# 实例：调试 Git 服务
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git

3.3 调试本地开发的 MCP 服务

TypeScript 项目

npx @modelcontextprotocol/inspector node path/to/server/index.js args...

Python 项目

npx @modelcontextprotocol/inspector \
  uv \
  --directory path/to/server \
  run \
  package-name \
  args...

4. 使用界面

调试服务启动成功后，会看到类似以下的输出：

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

访问提示的链接 (如 http://127.0.0.1:6274) 即可打开 Inspector 界面。

4.1 服务器连接面板

• 点击 “Connect” 按钮连接到 MCP 服务（这将启动您的目标服务）
• 可以选择连接的传输方式
• 对于本地服务，可以自定义命令行参数和环境变量

4.2 Resources 标签页

• 列出所有可用的资源
• 显示资源元数据（MIME 类型、描述）
• 允许检查资源内容
• 支持订阅测试

4.3 Prompts 标签页

• 显示可用的提示模板
• 显示提示参数和描述
• 可使用自定义参数测试提示
• 预览生成的消息

4.4 Tools 标签页

• 列出可用的工具和方法
• 显示工具模式和描述
• 可以使用自定义输入测试工具
• 显示工具执行结果
• 点击方法后，根据方法参数进行交互式调试

4.5 Notifications 面板

• 显示从服务器记录的所有日志
• 显示从服务器接收的通知

5. 开发工作流最佳实践

1. 开始开发

   • 使用 Inspector 启动您的服务器
   • 验证基本连接性
   • 检查功能协商

2. 迭代测试

   • 进行服务器更改
   • 重建服务器
   • 重新连接 Inspector
   • 测试受影响的功能
   • 监控消息

3. 测试边缘情况

   • 无效输入
   • 缺少提示参数
   • 并发操作
   • 验证错误处理和错误响应

6. 常见问题排查

如果您在使用 MCP Inspector 时遇到问题：

1. 确保端口没有被其他应用占用
2. 检查服务器代码中的日志记录
3. 使用 Inspector 中的通知面板查看详细错误
4. 检查命令行参数是否正确

7. 结论与进阶资源

MCP Inspector 是开发、测试和调试 MCP 服务不可或缺的工具。掌握它将大大提高您的开发效率。

进一步学习：

• MCP Inspector 源代码
• MCP 调试指南
• MCP 核心架构