MCP 检查器

MCP 检查器是一个用于测试和调试 MCP 服务器的开发者工具。

运行检查器

要求

• Node.js: ^22.7.5

从 MCP 服务器仓库运行

要检查 MCP 服务器的实现，无需克隆此仓库。可以直接使用 npx。例如，如果你的服务器构建在 build/index.js 中：

npx @modelcontextprotocol/inspector node build/index.js

你可以向你的 MCP 服务器传递参数和环境变量。参数直接传递给服务器，而环境变量可以通过 -e 标志设置：

# 仅传递参数
npx @modelcontextprotocol/inspector node build/index.js arg1 arg2

# 仅传递环境变量
npx @modelcontextprotocol/inspector -e key=value -e key2=$VALUE2 node build/index.js

# 同时传递环境变量和参数
npx @modelcontextprotocol/inspector -e key=value -e key2=$VALUE2 node build/index.js arg1 arg2

# 使用 -- 分隔检查器标志和服务器参数
npx @modelcontextprotocol/inspector -e key=$VALUE -- node build/index.js -e server-flag

检查器会同时运行 MCP 检查器（MCPI）客户端 UI（默认端口 6274）和 MCP 代理（MCPP）服务器（默认端口 6277）。在浏览器中打开 MCPI 客户端 UI 以使用检查器。（这些端口分别来自 MCPI 和 MCPP 的 T9 拨号映射，作为助记符）。你可以根据需要自定义端口：

CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js

有关使用检查器的更多详细信息，请参阅 MCP 文档站点的检查器部分。有关调试帮助，请参阅 调试指南。

服务器文件导出

MCP 检查器提供了方便的按钮来导出服务器启动配置，以便在 Cursor、Claude Code 或检查器的 CLI 等客户端中使用。该文件通常称为 mcp.json。

• 服务器条目 - 将单个服务器配置条目复制到剪贴板。可以将其添加到 mcp.json 文件中的 mcpServers 对象中，并使用你喜欢的服务器名称。

  STDIO 传输示例：

  {
    "command": "node",
    "args": ["build/index.js", "--debug"],
    "env": {
      "API_KEY": "your-api-key",
      "DEBUG": "true"
    }
  }
  

  SSE 传输示例：

  {
    "type": "sse",
    "url": "http://localhost:3000/events",
    "note": "对于 SSE 连接，直接在客户端中添加此 URL"
  }
  

• 服务器文件 - 将完整的 MCP 配置文件结构复制到剪贴板，并将当前服务器配置添加为 default-server。可以直接保存为 mcp.json。

  STDIO 传输示例：

  {
    "mcpServers": {
      "default-server": {
        "command": "node",
        "args": ["build/index.js", "--debug"],
        "env": {
          "API_KEY": "your-api-key",
          "DEBUG": "true"
        }
      }
    }
  }
  

  SSE 传输示例：

  {
    "mcpServers": {
      "default-server": {
        "type": "sse",
        "url": "http://localhost:3000/events",
        "note": "对于 SSE 连接，直接在客户端中添加此 URL"
      }
    }
  }
  

这些按钮在你配置服务器设置后出现在检查器 UI 中，方便保存和重用配置。

对于 SSE 传输连接，检查器为两个按钮提供了类似的功能。“服务器条目”按钮复制 SSE URL 配置，可以将其添加到现有配置文件中，而“服务器文件”按钮创建一个包含 SSE URL 的完整配置文件，以便直接在客户端中使用。

你可以将服务器条目粘贴到现有的 mcp.json 文件中你选择的服务器名称下，或使用完整的服务器文件负载创建新的配置文件。

认证

检查器支持 SSE 连接的承载令牌认证。在连接到 MCP 服务器时在 UI 中输入你的令牌，它将在 Authorization 标头中发送。你可以使用侧边栏中的输入字段覆盖标头名称。

安全注意事项

MCP 检查器包含一个代理服务器，可以运行并与本地 MCP 进程通信。代理服务器不应暴露给不受信任的网络，因为它具有生成本地进程的权限，并且可以连接到任何指定的 MCP 服务器。

配置

MCP 检查器支持以下配置设置。要更改它们，请单击 MCP 检查器 UI 中的 Configuration 按钮：

这些设置可以通过 UI 实时调整，并在会话之间持久化。

检查器还支持配置文件来存储不同 MCP 服务器的设置。这在处理多个服务器或复杂配置时非常有用：

npx @modelcontextprotocol/inspector --config path/to/config.json --server everything

示例服务器配置文件：

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-everything"],
      "env": {
        "hello": "Hello MCP!"
      }
    },
    "my-server": {
      "command": "node",
      "args": ["build/index.js", "arg1", "arg2"],
      "env": {
        "key": "value",
        "key2": "value2"
      }
    }
  }
}

提示： 你可以使用检查器 UI 中的 服务器条目 和 服务器文件 按钮轻松生成此配置格式，如上文服务器文件导出部分所述。

你还可以通过查询参数设置初始的 transport 类型、serverUrl、serverCommand 和 serverArgs，例如：

http://localhost:6274/?transport=sse&serverUrl=http://localhost:8787/sse
http://localhost:6274/?transport=streamable-http&serverUrl=http://localhost:8787/mcp
http://localhost:6274/?transport=stdio&serverCommand=npx&serverArgs=arg1%20arg2

你也可以通过查询参数设置初始配置设置，例如：

http://localhost:6274/?MCP_SERVER_REQUEST_TIMEOUT=10000&MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=false&MCP_PROXY_FULL_ADDRESS=http://10.1.1.22:5577

请注意，如果同时设置了查询参数和相应的 localStorage 项，查询参数将优先。

从此仓库运行

如果你正在开发检查器本身：

开发模式：

npm run dev

Windows 用户注意： 在 Windows 上，请改用以下命令：

npm run dev:windows

生产模式：

npm run build
npm start

CLI 模式

CLI 模式支持从命令行与 MCP 服务器进行程序化交互，非常适合脚本编写、自动化和与编码助手集成。这为 MCP 服务器开发创建了高效的反馈循环。

npx @modelcontextprotocol/inspector --cli node build/index.js

CLI 模式支持跨工具、资源和提示的大多数操作。以下是一些示例：

# 基本用法
npx @modelcontextprotocol/inspector --cli node build/index.js

# 使用配置文件
npx @modelcontextprotocol/inspector --cli --config path/to/config.json --server myserver

# 列出可用工具
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# 调用特定工具
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name mytool --tool-arg key=value --tool-arg another=value2

# 列出可用资源
npx @modelcontextprotocol/inspector --cli node build/index.js --method resources/list

# 列出可用提示
npx @modelcontextprotocol/inspector --cli node build/index.js --method prompts/list

# 连接到远程 MCP 服务器
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com

# 在远程服务器上调用工具
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --method tools/call --tool-name remotetool --tool-arg param=value

# 列出远程服务器的资源
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --method resources/list

UI 模式与 CLI 模式：何时使用

许可证

本项目采用 MIT 许可证—详情请参阅 LICENSE 文件。