使用说明

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

服务器将启动，用户界面将可在以下位置访问 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 标志：

# Pass arguments only
npx @modelcontextprotocol/inspector node build/index.js arg1 arg2

# Pass environment variables only
npx @modelcontextprotocol/inspector -e key=value -e key2=$VALUE2 node build/index.js

# Pass both environment variables and arguments
npx @modelcontextprotocol/inspector -e key=value -e key2=$VALUE2 node build/index.js arg1 arg2

# Use -- to separate inspector flags from server arguments
npx @modelcontextprotocol/inspector -e key=$VALUE -- node build/index.js -e server-flag

检查器运行MCP检查器（MCPI）客户端UI（默认端口6274）和MCP代理（MCPP）服务器（默认端口A/62/77）。在浏览器中打开MCPI客户端UI以使用检查器。（这些端口分别来自MCPI和MCPP的T9拨号盘映射，作为助记符）。如果需要，您可以自定义端口：

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

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

服务器文件导出

MCP Inspector提供了方便的按钮，用于导出服务器启动配置，以供Cursor、Claude Code或Inspector的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": "For SSE connections, add this URL directly in Client"
}

流式HTTP传输示例：

{
  "type": "streamable-http",
  "url": "http://localhost:3000/mcp",
  "note": "For Streamable HTTP connections, add this URL directly in your MCP Client"
}

服务器文件 -将完整的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": "For SSE connections, add this URL directly in Client"
    }
  }
}

流式HTTP传输示例：

{
  "mcpServers": {
    "default-server": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "note": "For Streamable HTTP connections, add this URL directly in your MCP Client"
    }
  }
}

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

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

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

认证

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

安全注意事项

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

认证

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

🔑 Session token: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

🔗 Open inspector with token pre-filled:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

此令牌必须作为Bearer令牌包含在对服务器的所有请求的Authorization标头中。检查员将自动打开您的浏览器，并在URL中预先填写令牌。

自动打开浏览器 -启用身份验证后，检查器现在会自动打开您的浏览器，并在URL中预先填写令牌。

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

点击侧边栏中的“配置”按钮
找到“代理会话令牌”并输入代理控制台中显示的令牌
点击“保存”应用配置

令牌将保存在浏览器的本地存储中以供将来使用。

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

DANGEROUSLY_OMIT_AUTH=true npm start

🚨 警告🚨

正在禁用身份验证 DANGEROUSLY_OMIT_AUTH 非常危险！禁用身份验证会使您的计算机不仅在暴露于公共互联网时容易受到攻击，而且 通过您的网络浏览器。这意味着，访问恶意网站或查看恶意广告可能会让攻击者远程入侵您的计算机。除非您真正了解风险，否则不要禁用此功能。

在Oligo的博客上阅读更多关于此漏洞的风险：人工MCP检查器中的关键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检查器会验证 Origin 传入请求的标头。默认情况下，只允许来自客户端源的请求（尊重 CLIENT_PORT 如果设置，则默认为端口6274）。您可以通过设置来配置其他允许的来源 ALLOWED_ORIGINS 环境变量（逗号分隔列表）：

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

配置

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

设置	说明	默认值
`MCP_SERVER_REQUEST_TIMEOUT`	客户端超时（毫秒）-如果在此时间内没有收到响应，检查器将取消请求。注意：服务器可能有自己的超时	300000
`MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS`	重置进度通知超时	true
`MCP_REQUEST_MAX_TOTAL_TIMEOUT`	发送到MCP服务器的请求的最大总超时时间（ms）（与进度通知一起使用）	60000
`MCP_PROXY_FULL_ADDRESS`	如果您在非默认地址上运行MCP检查器代理，请设置此选项。例子：http://10.1.1.22:5577	""
`MCP_AUTO_OPEN_ENABLED`	在检查器启动时启用自动浏览器打开（在启用身份验证的情况下工作）。仅作为环境变量，不可在浏览器中配置。	真的

关于超时的说明： 上述超时设置控制检查器（作为MCP客户端）何时取消请求。这些与任何服务器端超时无关。例如，如果服务器工具有10分钟的超时，但检查器的超时设置为30秒，检查器将在30秒后取消请求。相反，如果检查器的超时为10分钟，但服务器在30秒后超时，您将收到服务器的超时错误。对于需要用户交互（如启发）或长时间运行操作的工具，请确保适当设置检查器的超时。

这些设置可以通过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"
      }
    }
  }
}

配置文件中的传输类型

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

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"
    }
  }
}

默认服务器选择

如果您的配置有以下内容，您可以在不指定服务器名称的情况下启动检查器：

单一服务器 -自动选择：

# Automatically uses "my-server" if it's the only one
npx @modelcontextprotocol/inspector --config mcp.json

名为“默认服务器”的服务器 -自动选择：

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

提示： 您可以使用以下工具轻松生成此配置格式 服务器条目 和 服务器文件 检查器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=60000&MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=false&MCP_PROXY_FULL_ADDRESS=http://10.1.1.22:5577

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

来自此存储库

如果您正在处理检查员本身：

开发模式：

npm run dev

# To co-develop with the typescript-sdk package (assuming it's cloned in ../typescript-sdk; set MCP_SDK otherwise):
npm run dev:sdk "cd sdk && npm run examples:simple-server:w"
# then open http://localhost:3000/mcp as SHTTP in the inspector.
# To go back to the deployed SDK version:
#   npm run unlink:sdk && npm i

Windows用户注意事项： 在Windows上，请改用以下命令：
npm run dev:windows

生产方式：

npm run build
npm start

命令行接口命令模式

CLI模式允许从命令行与MCP服务器进行编程交互，是脚本编写、自动化和与编码助手集成的理想选择。这为MCP服务器开发创建了一个高效的反馈循环。

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

CLI模式支持跨工具、资源和提示的大多数操作。举几个例子：

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

# With config file
npx @modelcontextprotocol/inspector --cli --config path/to/config.json --server myserver

# List available tools
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# Call a specific tool
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name mytool --tool-arg key=value --tool-arg another=value2

# Call a tool with JSON arguments
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name mytool --tool-arg 'options={"format": "json", "max_tokens": 100}'

# List available resources
npx @modelcontextprotocol/inspector --cli node build/index.js --method resources/list

# List available prompts
npx @modelcontextprotocol/inspector --cli node build/index.js --method prompts/list

# Connect to a remote MCP server (default is SSE transport)
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com

# Connect to a remote MCP server (with Streamable HTTP transport)
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --method tools/list

# Connect to a remote MCP server (with custom headers)
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --method tools/list --header "X-API-Key: your-api-key"

# Call a tool on a remote server
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --method tools/call --tool-name remotetool --tool-arg param=value

# List resources from a remote server
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --method resources/list

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

用例	UI模式	CLI模式
服务器开发	用于开发过程中交互式测试和调试的可视化界面	用于快速测试和持续集成的可脚本化命令；使用Cursor等AI编码助手创建反馈循环，以实现快速开发
资源勘探	具有分层导航和JSON可视化功能的交互式浏览器	用于自动化和脚本编写的程序化列表和阅读
工具测试	基于表单的参数输入，实时响应可视化	命令行工具执行，JSON输出用于脚本编写
提示工程	具有流式响应和视觉比较的交互式采样	具有机器可读输出的提示的批处理
调试	请求历史记录、可视化错误和实时通知	直接JSON输出用于日志分析并与其他工具集成
自动化	N/A	是CI/CD管道、批处理和与编码助手集成的理想选择
学习MCP	丰富的可视化界面帮助新用户了解服务器功能	简化命令，集中学习特定端点

工具输入验证指南

在检查器中实施或修改工具输入参数处理时：

省略空值的可选字段 -处理表单输入时，省略可选参数的空字符串或null值，除非该字段在架构中具有与当前值匹配的显式默认值
保留显式默认值 -如果字段模式包含显式默认值（例如。， default: null)，并且当前值与默认值匹配，则将其包含在请求中。这是工具所期望的有意义的值
始终包含必填字段 -即使为空，也保留所需的字段值，允许MCP服务器验证并返回适当的错误消息
将深度验证推迟到服务器 -在Inspector客户端中实现基本的字段存在检查，但根据其模式依赖MCP服务器进行参数验证

这些准则保持了干净的参数传递和Inspector客户端和MCP服务器之间的适当关注点分离。

许可证

该项目根据MIT许可证获得许可——请参阅许可证文件以获取详细信息。