MCP Inspector：MCP服务器调试与测试工具 - 学习笔记-流行MCP服务器

一、MCP Inspector简介

MCP Inspector 是由 Anthropic 官方提供的 MCP 服务器交互式调试和测试工具。它让开发者无需编写任何客户端代码，即可通过 Web 图形界面直接与 MCP 服务器进行交互，检查服务器声明的工具、资源和提示模板，发送请求并查看响应结果。

在 MCP 服务器的开发流程中，Inspector 扮演着"开发调试器"的关键角色。每当开发者构建或修改一个 MCP 服务器时，都需要验证服务器是否正确实现了 MCP 协议规范、工具调用是否正常返回结果、资源读取是否按预期工作。借助 Inspector，这些验证工作变得直观而高效。

Inspector 的核心价值在于它大大降低了 MCP 服务器开发和调试的门槛。传统调试方式需要开发者自己编写测试脚本或搭建客户端环境，而 Inspector 开箱即用，一个 npx 命令就能启动完整的交互式测试环境。它支持的 MCP 传输协议包括标准的 stdio（标准输入输出）和 SSE（Server-Sent Events）两种模式，兼容绝大多数 MCP 服务器的连接方式。

零代码测试

无需编写客户端代码，通过Web界面即可完成所有MCP协议的测试操作，大幅提升开发效率。

实时日志监控

完整显示客户端和服务器之间的所有JSON-RPC消息交换，帮助开发者理解协议细节和排查问题。

多协议支持

同时支持stdio和SSE两种MCP传输协议，兼容本地运行的服务器和远程部署的服务器。

快捷检查

一键查看服务器所有能力（Tools、Resources、Prompts），快速验证服务器的功能清单是否完整。

二、安装与启动

2.1 通过 npx 直接运行

MCP Inspector 以 npm 包的形式发布，最简单的方式是通过 npx 直接运行，无需全局安装：

npx @anthropic/mcp-inspector

执行上述命令后，Inspector 会启动一个本地 Web 服务器，默认监听在 5173 端口。打开浏览器访问 http://localhost:5173 即可进入 Inspector 的主界面。首次使用时，会自动下载所需的依赖包，后续启动将更为快速。

2.2 连接本地 stdio MCP 服务器

Inspector 启动后，界面会显示一个连接配置面板。对于通过 stdio 协议通信的本地 MCP 服务器，需要在配置面板中填写服务器的启动命令。例如，如果要测试一个基于 Python 的 MCP 服务器，可以输入：

python -m my_mcp_server

如果是 Node.js 编写的 MCP 服务器：

node dist/server.js

在配置面板中填写完命令后，点击"Connect"按钮，Inspector 会启动该服务器进程并通过 stdio 与之建立连接。连接成功后，Inspector 会自动向服务器发送初始化请求，获取服务器的能力声明（包括支持的工具列表、资源列表和提示模板列表）。

2.3 连接远程 SSE MCP 服务器

对于部署在远程服务器上、通过 SSE 协议通信的 MCP 服务器，Inspector 同样支持连接。在配置面板中切换到 SSE 模式，填写服务器的 SSE 端点 URL：

https://example.com/mcp/sse

Inspector 会通过 HTTP 连接到 SSE 端点，建立持久化连接并发送初始化请求。连接远程服务器时需要注意网络可达性和跨域问题。对于本地开发中通过 SSE 运行的服务器，通常使用 http://localhost:PORT/sse 格式的 URL。

提示： 对于本地测试，推荐优先使用 stdio 模式。SSE 模式更适合测试已经部署的服务或需要模拟真实网络环境的场景。如果需要在 SSE 模式下传递自定义 HTTP 头（如认证令牌），Inspector 配置面板也提供了相应的设置选项。

三、界面导航

MCP Inspector 的 Web 界面布局清晰，主要分为以下几个核心区域：

3.1 左侧面板：连接的服务器列表

左侧面板显示当前已经连接的 MCP 服务器列表。如果同时连接了多个服务器实例（高级用法），可以在列表中快速切换，选择要调试的目标服务器。每个服务器条目会显示其名称、连接状态（已连接/断开）以及协议类型（stdio/SSE）。

3.2 主面板：工具/资源/提示三个标签页

主面板是 Inspector 的核心操作区域，通过三个标签页分别对应 MCP 协议的三大原语：

Tools 标签页： 展示服务器声明的所有工具列表，包含每个工具的 JSON Schema 参数定义。开发者可以选择工具、填写参数、执行调用并查看返回结果。
Resources 标签页： 展示服务器提供的所有资源列表，以 URI 树形结构呈现。点击资源可查看其元数据，点击"Read"按钮可读取资源内容。
Prompts 标签页： 展示服务器定义的所有提示模板。选择模板后可查看模板参数，填入参数值并生成最终的提示文本。

3.3 右侧面板：请求/响应日志查看

右侧面板实时显示客户端和服务器之间的全部消息交换记录。每条日志条目包含消息方向（发送/接收）、消息类型（initialize、tools/list、tools/call 等）、JSON-RPC 请求 ID 以及时间戳。点击任意日志条目可以在底部控制台查看完整的消息内容。

3.4 底部控制台：消息详情和调试输出

底部控制台区域展示被选中日志消息的完整 JSON-RPC 消息体，包括请求参数和响应结果的全部字段。此外，服务器写入 stderr 的调试日志也会在此处显示，方便开发者查看服务器端的运行状态和错误信息。

MCP Inspector 的界面设计遵循"先概览后细节"的原则：左侧的服务器列表和顶部的标签页提供概览，右侧的消息日志展示交互历史，底部的控制台呈现最详细的协议消息内容。这种分层设计让开发者既能够快速定位问题，又能够深入查看细节。点击复制

四、测试 Tools（工具）

4.1 查看服务器声明的所有工具

连接 MCP 服务器成功后，切换到"Tools"标签页，Inspector 会自动调用 tools/list 接口，获取服务器注册的全部工具列表。每个工具条目会显示工具名称、描述信息以及参数的 JSON Schema 定义。通过 Schema 可以了解到每个参数的类型（string、number、boolean、object、array 等）、是否必填、默认值以及枚举值约束。

4.2 选择工具并填写参数

点击需要测试的工具名称，Inspector 会展开一个参数输入面板。面板根据工具的 JSON Schema 自动生成表单控件——字符串类型生成文本框，数值类型生成数字输入框，布尔类型生成复选框，枚举类型生成下拉选择框。开发者只需填入测试参数即可，无需手动构造 JSON 请求体。

对于没有参数的简单工具，点击"Call Tool"按钮即可直接调用。对于参数较多的复杂工具，可以逐步填写不同字段，观察不同参数组合对返回结果的影响。

4.3 查看调用结果

点击"Call Tool"按钮后，Inspector 会构造 JSON-RPC 请求并发送给 MCP 服务器。调用完成后，结果区域会清晰展示：

成功结果： 显示工具返回的数据内容，支持格式化 JSON 展示，方便查看复杂数据结构的嵌套关系。
错误信息： 如果工具调用出错（如参数校验失败、内部计算异常），Inspector 会显示错误码和错误消息。同时右侧消息日志中会记录完整的错误 JSON-RPC 响应。
调用耗时： 每条工具调用记录旁边会显示耗时信息，帮助开发者评估工具的性能表现。

4.4 测试不同参数组合

Inspector 的一个强大功能是可以快速测试同一工具的不同参数组合。开发者可以修改参数值后重新调用，之前的调用记录会保留在右侧日志面板中，方便对比不同参数下的返回结果差异。这种交互式调试方式非常适合在开发过程中验证工具的边界情况处理，例如测试空值参数、极大值参数、特殊字符参数等。

注意： 如果 MCP 服务器的工具具有副作用（如写入数据库、发送邮件、修改文件系统等），在 Inspector 中调用同样会触发这些操作。建议在测试环境中使用 Inspector，避免对生产环境造成意外影响。

五、测试 Resources（资源）和 Prompts（提示）

5.1 测试 Resources

切换到"Resources"标签页后，Inspector 会调用 resources/list 接口获取服务器提供的所有资源列表。资源以 URI 的形式组织，通常遵循特定的命名规范，例如：

file:///data/config.json
postgres://database/schema/public/tables
memory://notes/recent

Inspector 以树形结构展示资源 URI，开发者可以展开树节点浏览资源的层次关系。每个资源条目会显示 URI、名称、MIME 类型（如 text/plain、application/json）以及可选的描述信息。

点击资源条目旁的"Read"按钮，Inspector 会调用 resources/read 接口读取该资源的内容。读取结果会展示在内容区域，对于 JSON 格式的内容会自动进行语法高亮和格式化，对于纯文本内容则直接显示。如果资源读取失败（如 URI 不存在、权限不足），Inspector 会返回详细的错误信息，帮助开发者定位问题。

提示： Resources 测试的核心价值在于验证 URI 设计是否合理、资源内容格式是否符合预期、以及资源是否存在和可读。如果资源支持参数化 URI（如 file:///logs/{date}），可以在"Read"时填入具体的参数值进行测试。

5.2 测试 Prompts

切换到"Prompts"标签页，Inspector 会调用 prompts/list 接口获取服务器定义的所有提示模板。每个提示模板包含模板名称、描述信息以及参数定义。

点击一个提示模板后，参数输入面板会根据模板的参数 Schema 生成表单。填入参数值后点击"Get Prompt"按钮，Inspector 会调用 prompts/get 接口，生成最终的提示文本。生成的提示文本会展示在结果区域，开发者可以检查提示模板的变量替换是否正确、生成的内容是否完整、格式是否整洁。

测试 Prompts 的意义在于确保提示模板在不同参数下都能生成高质量的提示文本，特别是模板中的条件逻辑和变量插值功能需要做充分的边界测试。

Prompts 是 MCP 协议中容易被忽视但非常有价值的原语。通过 Inspector 测试 Prompt 模板，可以直观地看到模板引擎如何处理各种输入参数，这对于构建高质量的 AI 交互模板至关重要。点击复制

六、日志与调试

6.1 查看 JSON-RPC 消息交换

Inspector 的右侧日志面板记录了客户端和服务器之间的每一次消息交换。每条消息按照时间顺序排列，使用不同的颜色区分请求（蓝色）和响应（绿色），以及错误消息（红色）。日志格式清晰展示：

消息方向：→ 发送 / ← 接收
方法名称：initialize、tools/list、resources/read 等
请求 ID：用于关联请求和响应的唯一标识
时间戳：精确到毫秒的发送/接收时间

6.2 检查错误响应和异常堆栈

当 MCP 服务器返回错误响应时，Inspector 会高亮显示错误条目。点击错误消息会在底部控制台展示完整的错误信息，包括：

错误码： 如 -32600（Invalid Request）、-32603（Internal Error）等标准 JSON-RPC 错误码。
错误消息： 服务器返回的文本描述。
错误数据： 某些服务器会在 error.data 字段中附带更详细的错误信息，如 Python 异常堆栈、参数校验失败详情等。

对于服务器端的运行异常，Inspector 会捕获服务器写入 stderr 的输出并显示在底部控制台的"Server Output"区域。这对于调试服务器端的运行时错误非常有帮助——例如 Python 服务器中的 Traceback 信息或者 Node.js 服务器中的异常堆栈。

6.3 监控工具调用耗时

每条工具调用记录都会显示从发出请求到收到响应的完整耗时。开发者可以通过耗时数据初步判断工具的性能表现：

毫秒级响应：表示工具执行速度快，适合高频调用。
秒级响应：可能存在网络延迟或计算密集型操作。
超时响应：如果长时间无响应，MCP 协议有内置的超时机制，超时后 Inspector 会显示"Timeout"错误。

6.4 查看服务器 stderr 输出

这个功能对于调试 stdio 模式的 MCP 服务器尤为关键。在 stdio 模式下，stdout 用于 JSON-RPC 消息通信，而 stderr 则专门用于输出服务器的调试日志和错误信息。Inspector 会在底部控制台实时显示服务器的 stderr 输出流，开发者可以在其中添加自己的调试日志（如 log 语句、打印变量值等），帮助定位问题。

# 在 Python MCP 服务器中添加调试输出
import sys
print("正在处理工具调用: get_weather", file=sys.stderr, flush=True)

# 或使用 logging
import logging
logging.basicConfig(stream=sys.stderr, level=logging.DEBUG)
logging.debug("参数详情: %s", params)

七、实际应用场景

7.1 开发新的 MCP 服务器时快速验证功能

在全新开发一个 MCP 服务器时，Inspector 是最直接的功能验证工具。按照"开发-启动-测试"的快速迭代循环，开发者可以：

在实现 tools/list 和 tools/call 后立即验证工具能否被正确发现和调用。
在添加新工具时测试参数校验逻辑和返回格式是否符合预期。
在重构代码后使用回归测试，确认核心功能没有受影响。
验证错误处理逻辑：发送非法参数、断开连接、模拟服务器内部异常等场景。

7.2 排查现有 MCP 服务器的连接和调用问题

当 MCP 客户端（如 Claude Desktop）无法正常连接或使用某个 MCP 服务器时，Inspector 是首选的故障排查工具：

连接问题： 先在 Inspector 中尝试连接，确认服务器进程是否能正常启动、初始化握手是否成功。
工具调用失败： 直接在 Inspector 中调用出现问题的工具，查看具体的错误信息和服务器输出。
资源不可用： 测试资源读取功能，确认 URI 地址是否正确、资源内容格式是否有效。
协议兼容性： 检查 JSON-RPC 消息格式是否符合规范，Inspector 会按规范严格校验。

7.3 学习理解 MCP 协议的消息交互过程

对于刚开始学习 MCP 协议的开发者来说，Inspector 是一个极好的学习工具。通过观察 Inspector 右侧面板中每条 JSON-RPC 消息的完整内容，可以直观理解 MCP 协议的各个生命周期阶段：

初始化阶段： 了解客户端和服务器如何协商协议版本和能力。
发现阶段： 观察 tools/list、resources/list、prompts/list 的请求和响应结构。
操作阶段： 查看 tools/call、resources/read、prompts/get 的消息格式。
终止阶段： 了解会话结束时的消息交换流程。

MCP Inspector 不仅仅是一个调试工具，它还是一面镜子，真实地反映出 MCP 服务器内部的工作机制。每一次消息交换、每一个错误响应，都是理解 MCP 协议的活教材。点击复制

7.4 演示 MCP 服务器的能力给团队成员

在团队协作或产品演示场景中，Inspector 可以作为 MCP 服务器的"展示台"：

无需为演示编写专门的客户端代码，打开 Inspector 即可展示服务器的完整功能。
团队成员可以亲自操作 Inspector，尝试不同的工具调用和资源读取，直观感受服务器的能力。
在代码评审时，评审者可以用 Inspector 验证新增的功能是否正常工作。
技术文档中可以用 Inspector 的截图作为示例，直观说明工具和资源的使用方法。

最佳实践： 建议在 MCP 服务器的 README 或开发者文档中，加入使用 Inspector 进行测试的快速入门指南。这能够大大降低项目的新人上手难度，提升团队协作效率。

MCP Inspector 作为一个轻量级但功能强大的调试工具，已经成为 MCP 开发生态中不可或缺的组成部分。无论是 MCP 服务器开发者、MCP 客户端集成者，还是 MCP 协议的学习者，都能从 Inspector 中获得极大的帮助。掌握 Inspector 的使用方法，是高效开发 MCP 服务器的重要基础。