MCP Inspector 使用指南：轻松测试、调试 MCP 服务器

零一探秘
5,278 阅读9分钟

对于许多在开发 MCP Server 的工程师来说，调试功能常常是一个耗时且效率不高的过程。频繁的请求、响应检查以及问题定位，往往令人感到繁琐。恰巧我最近自己在开发mcp server的过程中，发现了一款能够显著提升开发、调试效率的必备工具：MCP Inspector。它能帮助我们对 MCP 服务器进行快速测试和调试，提高整体开发效率。

在这篇文章中主要介绍MCP Inspector的用法、实用示例以及故障排查技巧，帮助开发者们能够快速掌握并高效利用这款工具。

什么是 MCP Inspector？

MCP Inspector(github仓库地址：github.com/modelcontex…) 是一款专为测试和调试 MCP 服务器设计的开发者工具，它支持以下操作：

  • 便捷地向 MCP 服务器发送各类请求。
  • 直观地查看服务器返回的响应内容。
  • 协助排查 MCP 实现中的潜在问题。

MCP Inspector 最显著的优点之一是提供了直观的 UI 用户界面。这意味着开发者无需从零开始编写复杂的客户端代码或测试脚本，即可轻松地进行 MCP Server 功能的测试与调试。

为什么选择 MCP Inspector？

那么，为什么推荐选择 MCP Inspector 呢？原因在于其带来的诸多优势：

  1. 简化测试流程：通过图形界面直接执行服务器功能，省去了编写额外测试代码的环节。
  2. 加速调试过程：提供请求与响应的详细视图，有助于开发者迅速定位问题所在。
  3. 探索MCP Server的功能：能够清晰列出服务器提供的所有功能或称为“工具”，便于开发者全面了解。
  4. 加速迭代开发 ：在开发过程中，可以即时验证代码改动，加快迭代速度。
  5. 标准合规：帮助开发者验证其MCP Server的实现是否正确遵循 MCP 协议标准。

MCP Inspector 入门

接下来，我们将介绍如何启动 MCP Inspector、使用服务器参数或环境变量运行它，并通过界面与服务器互动。

前置条件

在使用 MCP Inspector 之前，请确保开发环境中已安装 Node.js，建议版本为 22.7.5 或更高（可通过 node -v 命令检查）。Node.js 是一个用于服务器端 JavaScript 开发的运行时环境。

另外，需要一个可供测试的 MCP 服务器。在这里,我使用 squential-thinking和我自己开发的 cloudflare-r2-mcp-server (github.com/lskun/sprin…

基本启动命令

接下来，通过下面的npx命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector <command_to_start_your_server> <参数1> <参数2>

该命令的作用是：它会同时启动 Inspector 的后端代理（默认端口 6277）和前端用户界面，并启动指定的 MCP Server进程。

访问界面：启动后打开浏览器，访问 http://127.0.0.1:6274（除非自定义了端口），即可进入 MCP Inspector 的操作界面。

使用参数和环境变量运行 MCP Inspector

我们可以在启动命令中为 MCP Server设置参数和环境变量。例如，我们在使用brave-search时，可以通过命令行指定BRAVE_API_KEY

  npx @modelcontextprotocol/inspector -e BRAVE_API_KEY=your_api_key npx -y @modelcontextprotocol/server-brave-search 

运行 MCP Inspector 时，它会启动两个主要组件：

  1. MCP Inspector (MCPI) 客户端界面 – 默认端口：6274
  2. MCP Proxy (MCPP) 服务器 – 默认端口：6277，作为前端界面与指定的 MCP Server之间的通信中介。

如果需要更改默认端口，可以通过设置环境变量来实现：

CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector <command_to_start_your_server>

在这里，CLIENT_PORT=8080 表示界面端口为 8080，SERVER_PORT=9000 表示代理服务器端口为 9000。

使用配置文件管理复杂设置

对于涉及多项设置或需要管理多个 MCP 服务器的场景，MCP Inspector 提供了使用配置文件的便利。这在需要频繁切换不同MCP Server配置的场景下很好用。

例如，当我们使用cursor配置mcp server时，可以通过--config指定cursor配置文件的方式启动： npx @modelcontextprotocol/inspector --config ~/.cursor/mcp.json --server cloudflare-r2-mcp-server

注意事项：

  • 使用配置文件时，--server <服务器名称> 参数是必填的。
  • 每次只能指定一个MCP Server。
  • 服务器名称需与配置文件中定义的键名一致（如下面的 fetch 或 cloudflare-r2-mcp-server）。

以下是我使用的示例cursor mcp.json配置文件：

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "cloudflare-r2-mcp-server": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.transport=STDIO",
        "-jar",
        "/path/to/spring-boot-ai-cloudflare-r2-mcp-server-0.0.1-SNAPSHOT.jar"
      ],
      "env": {
        "R2_ACCESS_KEY_ID": "your_access_key_id",
        "R2_SECRET_ACCESS_KEY": "your_r2_secret_access_key",
        "R2_ENDPOINT": "https://your_account_id.r2.cloudflarestorage.com"
      }
    }
  }
}

该配置文件定义了两个服务器配置：一个是fetch MCP Server，另一个是 cloudflare-r2-mcp-server。

启动 Inspector 后，在浏览器中打开界面（http://localhost:6274），接下来让我们通过cloudflare-r2-mcp-server这个mcp的调试过程来了解其主要功能：

演示示例：测试Cloudflare R2对象存储MCP Server

首先，我们通过下面的npx命令启动MCP Inspector

在界面左侧面板中，可以配置与 MCP 服务器的连接：

  1. 传输类型：选择传输方式（默认是 STDIO）。
  2. 命令：输入运行命令（如 npx、node、java 等）。
  3. 参数：指定命令行参数。
  4. 环境变量：为服务器设置环境变量。
  5. 配置：访问高级配置选项。

完成设置后，点击“Connect”按钮建立连接。

连接设置 - MCP Inspector

连接设置 - MCP Inspector

连接成功后，主界面将显示多个选项卡：

  1. 资源（Resources） ：浏览 MCP 服务器上的所有可用资源，查看其元数据（如 MIME 类型），检查资源内容，并测试动态资源的订阅功能。
  2. 提示模板（Prompts） ：查看和测试提示模板及其参数，预览生成的文本，方便快速迭代和调试。
  3. 工具（Tools） ：与服务器提供的工具进行交互和测试。
  4. Ping：检查MCP Server是否正常响应。
  5. 采样（Sampling） ：当服务器触发 LLM 采样请求时，相关信息会在此处显示，供用户审核与批准。
  6. 根目录（Roots） ：用于配置服务器有权限访问的本地目录。

使用工具选项卡

“Tools”选项卡特别适合测试服务器功能：

  1. 点击“Tools”选项卡。
  2. 点击“List Tools”按钮查看可用工具列表。
  3. 在左侧选择一个工具查看详情。
  4. 如需输入参数，提供相关内容。
  5. 点击“Run Tool”执行。
  6. 查看输出结果。

在点击List Tools后，我们可以看到mcp server提供的所有工具调用方法以及对应的描述：

接下来我们进行功能测试的演示：

  • 测试功能1- 列出Cloudflare R2所有的存储桶 ：点击Tool List中对应的Tool,点击Run Tool，如下图可以看到工具被正确执行

  • 测试功能2- 列出test这个存储桶中所有的存储对象 ：在这里我们可以通过参数的指定以及prefix（可以理解为存储的虚拟路径）， 这里的方法参数对应我们在Tool具体实现方法中声明的参数。

命令行模式：通过 CLI 使用 MCP Inspector

除了网页界面，MCP Inspector 还提供命令行界面（CLI）模式，可以直接通过终端来调试 MCP server，非常适合自动化任务和脚本编写。

下面这是一个基于CLI模式的启动示例：

npx @modelcontextprotocol/inspector --cli --config ~/.cursor/mcp.json --server cloudflare-r2-mcp-server --method tools/list

注意：在 CLI 模式下，--method 参数是必填的，用于指定要调用的服务器方法，如工具或资源。

调用特定的工具listBuckets

调用特定的工具listBuckets

浏览器界面与命令行模式：如何选择？

这两种使用方式各有侧重，我们可以根据具体任务需求进行选择。以下是一个对比建议：

任务类型浏览器模式（UI）命令行模式（CLI）
探索新服务器更好 – 可视化浏览功能较难 – 需熟悉命令
开发中测试更好 – 视觉反馈便于发现问题一般 – 适合快速检查
自动化测试不适合最佳 – 可集成到脚本和 CI/CD
学习 MCP 原理更好 – 界面直观展示关系较难 – 需要更多基础知识
测试服务器功能（工具）更好 – 表单引导输入，结果直观清晰一般 – 适合重复测试，输出适于脚本
调试问题更好 – 历史记录和错误可视化一般 – 日志输出适合记录

对于初次接触或需要直观操作的场景，浏览器界面是更好的选择。而对于追求效率、自动化或需要集成到工作流的进阶用户，CLI 模式则提供了强大支持。

使用注意事项

使用 MCP Inspector 时，请注意以下几点：

  1. 安全性：MCP Inspector 是开发工具，谨慎处理发送的数据和连接的服务器。
  2. 资源占用：同时运行服务器和 Inspector 可能消耗较多资源，注意内存和 CPU 使用情况。
  3. 配置管理：管理好配置文件，尤其是在处理多个 MCP 服务器时。
  4. 网络问题：Inspector 使用本地端口通信，确保端口未被防火墙或其他安全措施阻止。
  5. 超时处理：若服务器操作耗时较长，可在配置面板调整超时设置。

常见问题解答（FAQ）

MCP Inspector 与普通 MCP 客户端有什么不同？
MCP Inspector 提供可视化界面，专注于调试和测试；而普通客户端通常是程序代码，用于生产环境中与服务器交互。

MCP Inspector 是否适用于所有 MCP 服务器？
是的，MCP Inspector 的设计就是为与任何符合 MCP 协议的服务器实现兼容，不论使用何种编程语言或框架。

UI 模式与 CLI 模式有何不同？
UI 模式提供浏览器中的图形界面，适合交互式探索和视觉反馈；CLI 模式则在终端中运行，更适合自动化、脚本编写以及与其他开发工具的集成。

写在最后

总的来说，MCP Inspector 是 MCP 开发者的实用工具，它通过简洁的界面，极大地简化了对 MCP 服务器的测试、调试和交互过程。通过上述内容，相信你对MCP Inspector 的使用已经有了一定的了解，在进行 MCP Server的相关开发时通过MCP Inspector的使用一定会让你事半功倍。好了，今天的分享就这些，有问题可以在评论区交流~

avatar
文章
阅读
粉丝