MCP 检查器

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

架构概览

MCP 检查器由两个主要组件协同工作组成：

• MCP 检查器客户端 (MCPI)：基于 React 的 Web UI，提供用于测试和调试 MCP 服务器的交互式界面。
• MCP 代理 (MCPP)：一个 Node.js 服务器，充当协议桥接层，通过多种传输方式（stdio、SSE、可流式 HTTP）将 Web UI 连接到 MCP 服务器。

请注意，该代理并非用于拦截流量的网络代理。相反，它既作为 MCP 客户端（连接到您的 MCP 服务器），又作为 HTTP 服务器（为 Web UI 提供服务），从而实现浏览器与使用不同传输协议的 MCP 服务器之间的交互。

运行检查器

要求

• Node.js：^22.7.5

快速入门（UI 模式）

要立即启动并使用 UI，只需执行以下命令：

npx @modelcontextprotocol/inspector

服务器将启动，UI 可在 http://localhost:6274 访问。

Docker 容器

您也可以使用以下命令在 Docker 容器中启动它：

docker run --rm \
  -p 127.0.0.1:6274:6274 \
  -p 127.0.0.1:6277:6277 \
  -e HOST=0.0.0.0 \
  -e MCP_AUTO_OPEN_ENABLED=false \
  ghcr.io/modelcontextprotocol/inspector:latest

从 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 检查器客户端 UI（默认端口 6274）和 MCP 代理服务器（默认端口 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 添加到客户端中"
  }
  

  可流式 HTTP 传输示例：

  {
    "type": "streamable-http",
    "url": "http://localhost:3000/mcp",
    "note": "对于可流式 HTTP 连接，直接将此 URL 添加到您的 MCP 客户端中"
  }
  

• 服务器文件：将完整的 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 添加到客户端中"
      }
    }
  }
  

  可流式 HTTP 传输示例：

  {
    "mcpServers": {
      "default-server": {
        "type": "streamable-http",
        "url": "http://localhost:3000/mcp",
        "note": "对于可流式 HTTP 连接，直接将此 URL 添加到您的 MCP 客户端中"
      }
    }
  }
  

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

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

您可以将“服务器条目”粘贴到现有的 mcp.json 文件中，并以您选择的服务器名称命名；或者使用完整的“服务器文件”载荷来创建新的配置文件。

身份验证

检查器支持 SSE 连接的 Bearer 令牌身份验证。在连接到 MCP 服务器时，请在 UI 中输入您的令牌，它将被发送到 Authorization 头中。您还可以使用侧边栏中的输入框覆盖头字段名称。

安全注意事项

MCP Inspector 包含一个代理服务器，该服务器可以运行并与本地 MCP 进程进行通信。由于代理服务器具有启动本地进程的权限，并且能够连接到任何指定的 MCP 服务器，因此不应将其暴露在不可信的网络中。

身份验证

MCP Inspector 代理服务器默认需要身份验证。在启动服务器时，会生成一个随机会话令牌并打印到控制台：

🔑 会话令牌: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

🔗 使用预填令牌打开检查器：
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

所有发送到该服务器的请求都必须在 Authorization 头部中包含此令牌作为 Bearer 令牌。检查器将自动使用预填了该令牌的 URL 打开您的浏览器。

自动打开浏览器 - 当启用身份验证时，检查器现在会自动使用预填了令牌的 URL 打开您的浏览器。

替代方案：手动配置 - 如果您已经打开了检查器：

1. 点击侧边栏中的“配置”按钮。
2. 找到“代理会话令牌”，并将代理控制台中显示的令牌输入其中。
3. 单击“保存”以应用配置。

该令牌将被保存在您的浏览器本地存储中，以便将来使用。

如果您需要禁用身份验证（不推荐），可以设置 DANGEROUSLY_OMIT_AUTH 环境变量：

DANGEROUSLY_OMIT_AUTH=true npm start

---

🚨 警告 🚨

使用 DANGEROUSLY_OMIT_AUTH 禁用身份验证是非常危险的！禁用身份验证不仅会在机器暴露于公共互联网时使其面临攻击风险，还会通过您的 Web 浏览器带来威胁。这意味着，访问恶意网站或查看恶意广告都可能导致攻击者远程攻陷您的计算机。请务必在充分了解相关风险的情况下再决定是否禁用此功能。

有关此漏洞风险的更多信息，请参阅 Oligo 的博客文章：Anthropic MCP Inspector 中的关键 RCE 漏洞 - CVE-2025-49596

---

您也可以在启动服务器时通过 MCP_PROXY_AUTH_TOKEN 环境变量设置令牌：

MCP_PROXY_AUTH_TOKEN=$(openssl rand -hex 32) npm start

仅限本地绑定

默认情况下，MCP Inspector 的代理服务器和客户端都只绑定到 localhost，以防止网络访问。这确保了它们无法从网络中的其他设备访问。如果您出于开发目的需要绑定到所有接口，可以通过设置 HOST 环境变量来覆盖此行为：

HOST=0.0.0.0 npm start

警告： 仅在受信任的网络环境中才应绑定到所有接口，因为这样会使代理服务器能够执行本地进程，并使两项服务暴露于网络访问之下。

DNS 重绑定防护

为防止 DNS 重绑定攻击，MCP Inspector 会对传入请求的 Origin 头部进行验证。默认情况下，仅允许来自客户端来源的请求（如果设置了 CLIENT_PORT，则会尊重该端口，默认为 6274）。您可以通过设置 ALLOWED_ORIGINS 环境变量（逗号分隔列表）来配置其他允许的来源：

ALLOWED_ORIGINS=http://localhost:6274,http://localhost:8000 npm start

配置

MCP Inspector 支持以下配置设置。要更改这些设置，请单击 MCP Inspector UI 中的 Configuration 按钮：

设置	描述	默认值
MCP_SERVER_REQUEST_TIMEOUT	客户端超时时间（毫秒）——如果在此时间内未收到响应，Inspector 将取消请求。注意：服务器可能有自己的超时设置	300000
MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS	在收到进度通知时重置超时时间	true
MCP_REQUEST_MAX_TOTAL_TIMEOUT	发送到 MCP 服务器的请求的最大总超时时间（毫秒）（需配合进度通知使用）	60000
MCP_PROXY_FULL_ADDRESS	如果您在非默认地址上运行 MCP Inspector Proxy，请设置此选项。例如：http://10.1.1.22:5577	""
MCP_AUTO_OPEN_ENABLED	启用 Inspector 启动时自动打开浏览器（需启用身份验证）。仅可通过环境变量设置，无法在浏览器中配置。	true

关于超时的说明： 上述超时设置控制着 Inspector（作为 MCP 客户端）何时会取消请求。这些设置与任何服务器端超时无关。例如，如果服务器工具的超时时间为 10 分钟，而 Inspector 的超时时间设置为 30 秒，则 Inspector 会在 30 秒后取消请求。相反，如果 Inspector 的超时时间为 10 分钟，但服务器在 30 秒后超时，您将收到服务器的超时错误。对于需要用户交互（如提示生成）或长时间运行的操作，务必合理设置 Inspector 的超时时间。

这些设置可以通过 UI 实时调整，并且将在会话之间保持不变。

Inspector 还支持配置文件，用于存储不同 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"
      }
    }
  }
}

配置文件中的传输类型

Inspector 会自动从您的配置文件中检测传输类型。您可以指定不同的传输类型：

STDIO（默认）：

{
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-everything"]
    }
  }
}

SSE（服务器发送事件）：

{
  "mcpServers": {
    "my-sse-server": {
      "type": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}

可流式 HTTP：

{
  "mcpServers": {
    "my-http-server": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

默认服务器选择

如果您在配置中设置了以下内容，可以在不指定服务器名称的情况下启动 Inspector：

1. 只有一个服务器——将自动选择该服务器：

# 如果只有“my-server”，则自动使用它
npx @modelcontextprotocol/inspector --config mcp.json

2. 有一个名为“default-server”的服务器——将自动选择该服务器：

{
  "mcpServers": {
    "default-server": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-everything"]
    },
    "other-server": {
      "command": "node",
      "args": ["other.js"]
    }
  }
}

提示： 您可以使用 Inspector UI 中的“Server Entry”和“Servers File”按钮轻松生成此配置格式，具体请参阅上述“Servers File Export”部分。

您还可以通过查询参数设置初始的 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=60000&MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=false&MCP_PROXY_FULL_ADDRESS=http://10.1.1.22:5577

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

来自本仓库

如果您正在开发 Inspector 自身：

开发模式：

npm run dev

# 若要与 typescript-sdk 包协同开发（假设它已克隆到 ../typescript-sdk；否则请设置 MCP_SDK）：
npm run dev:sdk "cd sdk && npm run examples:simple-server:w"
# 然后在 Inspector 中以 SHTTP 方式打开 http://localhost:3000/mcp。
# 若要恢复到已部署的 SDK 版本：
#   npm run unlink:sdk && npm i

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

# 使用 JSON 参数调用工具
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name mytool --tool-arg 'options={"format": "json", "max_tokens": 100}'

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

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

# 连接到远程 MCP 服务器（默认使用 SSE 传输）
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com

# 连接到远程 MCP 服务器（使用可流式 HTTP 传输）
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --method tools/list

# 连接到远程 MCP 服务器（带自定义头部）
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --method tools/list --header "X-API-Key: your-api-key"

# 在远程服务器上调用工具
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 模式：何时使用各自模式

使用场景	UI 模式	CLI 模式
服务器开发	开发过程中用于交互式测试和调试的可视化界面	可脚本化的命令，便于快速测试和持续集成；可与 Cursor 等 AI 编码助手形成反馈循环，加速开发
资源探索	带有层次化导航和 JSON 可视化的交互式浏览器	通过程序化方式列出并读取数据，适用于自动化和脚本编写
工具测试	基于表单的参数输入，并实时显示响应结果	通过命令行执行工具，并以 JSON 格式输出，便于脚本化
提示工程	支持流式响应的交互式采样及可视化对比	批量处理提示，并生成机器可读的输出
调试	请求历史记录、可视化的错误信息以及实时通知	直接输出 JSON 数据，便于日志分析及与其他工具集成
自动化	不适用	非常适合 CI/CD 流水线、批量处理以及与编码助手的集成
学习 MCP	丰富的可视化界面有助于新用户理解服务器功能	简化的命令，便于专注于特定端点的学习

工具输入验证指南

在 Inspector 中实现或修改工具输入参数处理时：

• 省略空值的可选字段 - 处理表单输入时，应省略可选参数中的空字符串或空值，除非该字段在模式中已明确设置了与当前值相同的默认值。
• 保留显式默认值 - 如果字段模式中包含显式的默认值（例如 default: null），且当前值与该默认值一致，则应在请求中包含该值。这是工具所期望的有意义的值。
• 始终包含必填字段 - 即使必填字段为空，也应将其保留在请求中，以便 MCP 服务器能够进行验证并返回适当的错误信息。
• 将深度验证交由服务器处理 - 在 Inspector 客户端中仅实现基本的字段存在性检查，而具体的参数验证则应依赖于 MCP 服务器根据其模式来进行。

这些指南有助于保持参数传递的整洁，并在 Inspector 客户端与 MCP 服务器之间实现合理的职责分离。

许可证

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

MCP Inspector 快速上手指南

MCP Inspector 是一款专为开发者设计的调试工具，用于测试和调试 MCP (Model Context Protocol) 服务器。它由基于 React 的 Web 界面（MCPI）和作为协议桥接的 Node.js 代理服务器（MCPP）组成，支持通过浏览器与使用不同传输协议（stdio, SSE, streamable-http）的 MCP 服务器进行交互。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本需为 ^22.7.5 或更高。
  • 建议使用 nvm 管理 Node 版本。
  • 国内用户可配置淘宝镜像加速安装：

    export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node/
    nvm install 22
    

• 浏览器: 现代浏览器（Chrome, Edge, Firefox 等）。
• Docker (可选): 如果选择容器化运行，需安装 Docker Desktop 或 Docker Engine。

安装与启动

MCP Inspector 无需手动克隆仓库或复杂安装，推荐使用 npx 直接运行，也可通过 Docker 启动。

方式一：使用 npx 快速启动（推荐）

这是最简单的启动方式，会自动下载并运行最新版本的 Inspector UI。

npx @modelcontextprotocol/inspector

启动成功后，终端会显示访问地址。默认情况下，Web 界面运行在 http://localhost:6274。浏览器通常会自动打开并填入认证令牌。

方式二：使用 Docker 启动

如果您偏好容器化环境，可以使用以下命令：

docker run --rm \
  -p 127.0.0.1:6274:6274 \
  -p 127.0.0.1:6277:6277 \
  -e HOST=0.0.0.0 \
  -e MCP_AUTO_OPEN_ENABLED=false \
  ghcr.io/modelcontextprotocol/inspector:latest

基本使用

1. 调试本地 MCP 服务器

假设您有一个已构建好的 MCP 服务器文件（例如 build/index.js），您可以直接通过 npx 命令将其传递给 Inspector 进行调试。

基本命令：

npx @modelcontextprotocol/inspector node build/index.js

传递参数与环境变量： 您可以向 MCP 服务器传递启动参数和环境变量：

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

# 仅传递环境变量
npx @modelcontextprotocol/inspector -e API_KEY=your-key -e DEBUG=true node build/index.js

# 同时传递环境变量和参数
npx @modelcontextprotocol/inspector -e API_KEY=your-key node build/index.js --verbose

# 使用 -- 分隔 Inspector 标志与服务器参数（防止参数冲突）
npx @modelcontextprotocol/inspector -e KEY=VAL -- node build/index.js -e server-flag

启动后，Inspector 会运行两个服务：

• Client UI: 默认端口 6274 (用于浏览器交互)
• Proxy Server: 默认端口 6277 (用于连接 MCP 服务器)

请在浏览器中打开 http://localhost:6274 开始调试。

2. 自定义端口

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

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

3. 导出服务器配置

在 Web 界面中配置好服务器连接后，您可以利用界面提供的按钮轻松导出配置文件，以便在 Cursor、Claude Code 或其他 MCP 客户端中复用：

• Server Entry: 复制单个服务器配置片段（JSON 格式），可粘贴到现有的 mcp.json 文件中。
• Servers File: 复制完整的 mcp.json 文件结构，包含当前配置的服务器（默认为 default-server）。

支持 STDIO、SSE 和 Streamable HTTP 等多种传输协议的配置导出。

4. 安全与认证说明

• 自动认证：启动时，工具会生成一个随机会话令牌（Session Token）并打印在控制台。浏览器会自动携带该令牌打开，无需手动输入。
• 手动配置：如果浏览器未自动打开，可在 UI 侧边栏点击 "Configuration"，将控制台输出的令牌填入 "Proxy Session Token" 并保存。
• ⚠️ 安全警告：
  • 切勿在生产环境或不受信任的网络中禁用认证。
  • 严禁设置 DANGEROUSLY_OMIT_AUTH=true，除非您完全理解其带来的远程代码执行（RCE）风险。
  • 默认情况下，服务仅绑定 localhost，禁止外部网络访问。如需局域网调试，可设置 HOST=0.0.0.0，但请务必确保网络安全。