内容
# MCP Inspector
MCP Inspector 是一个用于测试和调试 MCP 服务器的开发者工具。
## 架构概述
MCP Inspector 由两个主要组件组成，它们共同工作：
- **MCP Inspector Client (MCPI)**：一个基于 React 的 Web 界面，提供交互式界面用于测试和调试 MCP 服务器
- **MCP Proxy (MCPP)**：一个 Node.js 服务器，作为协议桥，连接 Web 界面与 MCP 服务器，通过各种传输方法（stdio、SSE、streamable-http）
注意，代理不是用于拦截流量的网络代理。相反，它既是 MCP 客户端（连接到您的 MCP 服务器），又是 HTTP 服务器（为 Web 界面提供服务），从而实现使用不同传输协议的 MCP 服务器的基于浏览器的交互。
## 运行 Inspector
### 要求
- Node.js: ^22.7.5
### 快速启动（UI 模式）
要立即启动并运行 UI，只需执行以下操作：
```bash
npx @modelcontextprotocol/inspector
```
服务器将启动，UI 将在 `http://localhost:6274` 上可访问。
### Docker 容器
您也可以使用以下命令在 Docker 容器中启动它：
```bash
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`：
```bash
npx @modelcontextprotocol/inspector node build/index.js
```
您可以将参数和环境变量传递给您的 MCP 服务器。参数直接传递给您的服务器，而环境变量可以使用 `-e` 标志设置：
```bash
# 只传递参数
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
# 使用 -- 分隔 inspector 标志和服务器参数
npx @modelcontextprotocol/inspector -e key=$VALUE -- node build/index.js -e server-flag
```
Inspector 运行 MCP Inspector（MCPI）客户端 UI（默认端口 6274）和 MCP Proxy（MCPP）服务器（默认端口 6277）。在浏览器中打开 MCPI 客户端 UI 以使用 inspector。（这些端口源自 MCPI 和 MCPP 分别的 T9 拨号盘映射，作为助记符）。如果需要，您可以自定义端口：
```bash
CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js
```
有关使用 inspector 的更多详细信息，请参阅 [MCP 文档站点的 Inspector 部分](https://modelcontextprotocol.io/docs/tools/inspector)。有关调试的帮助，请参阅 [调试指南](https://modelcontextprotocol.io/docs/tools/debugging)。
### 服务器文件导出
MCP Inspector 提供便捷的按钮，用于导出服务器启动配置，供 Cursor、Claude Code 或 Inspector 的 CLI 等客户端使用。该文件通常称为 `mcp.json`。
- **服务器条目** - 将单个服务器配置条目复制到剪贴板。可以将其添加到 `mcp.json` 文件中的 `mcpServers` 对象中，名称由您选择。
**STDIO 传输示例：**
```json
{
"command": "node",
"args": ["build/index.js", "--debug"],
"env": {
"API_KEY": "your-api-key",
"DEBUG": "true"
}
}
```
**SSE 传输示例：**
```json
{
"type": "sse",
"url": "http://localhost:3000/events",
"note": "对于 SSE 连接，请在客户端直接添加此 URL"
}
```
**Streamable HTTP 传输示例：**
```json
{
"type": "streamable-http",
"url": "http://localhost:3000/mcp",
"note": "对于 Streamable HTTP 连接，请在 MCP 客户端直接添加此 URL"
}
```
- **服务器文件** - 将完整的 MCP 配置文件结构复制到剪贴板，并将当前服务器配置添加为 `default-server`。可以直接保存为 `mcp.json`。
**STDIO 传输示例：**
```json
{
"mcpServers": {
"default-server": {
"command": "node",
"args": ["build/index.js", "--debug"],
"env": {
"API_KEY": "your-api-key",
"DEBUG": "true"
}
}
}
}
```
**SSE 传输示例：**
```json
{
"mcpServers": {
"default-server": {
"type": "sse",
"url": "http://localhost:3000/events",
"note": "对于 SSE 连接，请在客户端直接添加此 URL"
}
}
}
```
**Streamable HTTP 传输示例：**
```json
{
"mcpServers": {
"default-server": {
"type": "streamable-http",
"url": "http://localhost:3000/mcp",
"note": "对于 Streamable HTTP 连接，请在 MCP 客户端直接添加此 URL"
}
}
}
```
这些按钮在您配置好服务器设置后出现在 Inspector UI 中，可以轻松保存和重用配置。
对于 SSE 和 Streamable HTTP 传输连接，Inspector 为两个按钮提供类似的功能。“服务器条目”按钮复制可以添加到现有配置文件中的配置，而“服务器文件”按钮创建一个完整的配置文件，其中包含可以直接使用的 URL。
可以将服务器条目粘贴到现有的 `mcp.json` 文件中，名称由您选择，也可以将完整的服务器文件有效负载用于创建新的配置文件。
### 身份验证
Inspector 支持 SSE 连接的 bearer token 身份验证。在连接到 MCP 服务器时，在 UI 中输入您的 token，它将包含在授权头部中。您可以使用侧边栏中的输入字段覆盖头部名称。
### 安全考虑
MCP Inspector 包括一个可以运行和与本地 MCP 进程通信的代理服务器。代理服务器不应暴露在不受信任的网络中，因为它具有启动本地进程和连接到任何指定的 MCP 服务器的权限。
#### 身份验证
MCP Inspector 代理服务器默认需要身份验证。启动服务器时，会生成一个随机的会话令牌并打印到控制台：
```
🔑 会话令牌：3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4
🔗 使用预填充的令牌打开 inspector：
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4
```
此令牌必须作为 bearer token 包含在所有发送到服务器的请求的授权头部中。Inspector 将自动打开您的浏览器，并使用预填充的令牌 URL。
**自动打开浏览器** - 现在，Inspector 在启用身份验证时会使用预填充的令牌 URL 自动打开您的浏览器。
**替代：手动配置** - 如果您已经打开了 Inspector：
1. 点击侧边栏中的“配置”按钮
2. 找到“代理会话令牌”并输入显示的令牌
3. 点击“保存”以应用配置
令牌将保存在浏览器的本地存储中，以供将来使用。
如果需要禁用身份验证（不推荐），可以设置 `DANGEROUSLY_OMIT_AUTH` 环境变量：
```bash
DANGEROUSLY_OMIT_AUTH=true npm start
```
---
**🚨 警告 🚨**
禁用 `DANGEROUSLY_OMIT_AUTH` 极其危险！禁用身份验证会使您的机器暴露于攻击之下，不仅限于公网，还包括 **通过您的 Web 浏览器**。这意味着访问恶意网站或查看恶意广告可能会允许攻击者远程入侵您的计算机。请勿禁用此功能，除非您真正了解风险。
阅读 Oligo 博客上的更多风险信息：[Anthropic MCP Inspector 中的关键 RCE 漏洞 - CVE-2025-49596](https://www.oligo.security/blog/critical-rce-vulnerability-in-anthropic-mcp-inspector-cve-2025-49596)
---
您还可以在启动服务器时通过 `MCP_PROXY_AUTH_TOKEN` 环境变量设置令牌：
```bash
MCP_PROXY_AUTH_TOKEN=$(openssl rand -hex 32) npm start
```
#### 仅本地绑定
默认情况下，MCP Inspector 代理服务器和客户端仅绑定到 `localhost`，以防止网络访问。这确保它们仅在您的本地设备上可访问。如果您需要为开发目的绑定到所有接口，可以使用 `HOST` 环境变量覆盖此设置：
```bash
HOST=0.0.0.0 npm start
```
**警告：** 仅在受信任的网络环境中绑定到所有接口，因为这会将代理服务器执行本地进程的能力和两个服务对网络访问暴露在外。
#### DNS 重绑定保护
为了防止 DNS 重绑定攻击，MCP Inspector 验证传入请求的 `Origin` 头。默认情况下，只允许来自客户端源的请求（如果设置了 `CLIENT_PORT`，则默认为 6274 端口）。您可以通过设置 `ALLOWED_ORIGINS` 环境变量来配置其他允许的源（逗号分隔的列表）：
```bash
ALLOWED_ORIGINS=http://localhost:6274,http://localhost:8000 npm start
```
### 配置
MCP Inspector 支持以下配置设置。要更改它们，请点击 MCP Inspector UI 中的 `配置` 按钮：
| 设置 | 描述 | 默认值 |
| --- | --- | --- |
| `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 代理服务器，请设置此参数。例如：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 服务器的设置。这在处理多个服务器或复杂配置时很有用：
```bash
npx @modelcontextprotocol/inspector --config path/to/config.json --server everything
```
示例服务器配置文件：
```json
{
"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（默认）：**
```json
{
"mcpServers": {
"my-stdio-server": {
"type": "stdio",
"command": "npx",
"args": ["@modelcontextprotocol/server-everything"]
}
}
}
```
**SSE（服务器发送事件）：**
```json
{
"mcpServers": {
"my-sse-server": {
"type": "sse",
"url": "http://localhost:3000/sse"
}
}
}
```
**Streamable HTTP：
```json
{
"mcpServers": {
"my-http-server": {
"type": "streamable-http",
"url": "http://localhost:3000/mcp"
}
}
}
```
#### 默认服务器选择
如果您的配置文件中有：
1. **单个服务器** - 自动选择：
```bash
# 自动使用“my-server”，因为它是唯一一个
npx @modelcontextprotocol/inspector --config mcp.json
```
2. **名为“default-server”的服务器** - 自动选择：
```json
{
"mcpServers": {
"default-server": {
"command": "npx",
"args": ["@modelcontextprotocol/server-everything"]
},
"other-server": {
"command": "node",
"args": ["other.js"]
}
}
}
```
> **提示：** 您可以使用 Inspector 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 项，则查询参数将优先。
### 从此仓库
如果您正在开发 inspector 本身：
开发模式：
```bash
npm run dev
# 与 typescript-sdk 包（假设它克隆在 ../typescript-sdk 中；设置为 MCP_SDK）
npm run dev:sdk "cd sdk && npm run examples:simple-server:w"
# 然后在 inspector 中将 http://localhost:3000/mcp 作为 SHTTP
# 要恢复到部署的 SDK 版本：
# npm run unlink:sdk && npm i
```
> **Windows 用户注意：>
> 在 Windows 上，请使用以下命令：
> ```bash
> npm run dev:windows
> ```
生产模式：
```bash
npm run build
npm start
```
### CLI 模式
CLI 模式允许从命令行与 MCP 服务器进行编程交互，适用于脚本、自动化以及与代码助手集成。这样就创建了一个高效的 MCP 服务器开发反馈循环。
```bash
npx @modelcontextprotocol/inspector --cli node build/index.js
```
CLI 模式支持大多数工具、资源和提示的操作。以下是一些示例：
```bash
# 基本用法
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 服务器（使用 Streamable 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
```
### 界面模式 vs 命令行模式：何时使用每种模式
| 使用场景 | 界面模式 | 命令行模式 |
| ------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **服务器开发** | 用于开发过程中的交互式测试和调试的视觉界面 | 用于快速测试和持续集成的可脚本命令；与 Cursor 等 AI 编码助手创建反馈循环以实现快速开发 |
| **资源探索** | 具有层次导航和 JSON 可视化的交互式浏览器 | 用于自动化和脚本编程的编程列表和读取 |
| **工具测试** | 基于表单的参数输入，实时响应可视化 | 命令行工具执行，带有 JSON 输出用于脚本编写 |
| **提示工程** | 具有流式响应和视觉比较的交互式采样 | 提示的批处理，带有机器可读输出 |
| **调试** | 请求历史、视觉错误和实时通知 | 直接 JSON 输出，用于日志分析和与其他工具集成 |
| **自动化** | 不适用 | 适用于 CI/CD 管道、批处理以及与编码助手集成 |
| **学习 MCP** | 丰富的视觉界面帮助新用户了解服务器功能 | 用于特定端点聚焦学习的简化命令 |
## 工具输入验证指南
在检查器中实现或修改工具输入参数处理时：
- **省略具有空值的可选字段** - 处理表单输入时，对于可选参数省略空字符串或空值，除非字段在架构中具有与当前值匹配的显式默认值
- **保留显式默认值** - 如果字段架构包含显式默认值（例如 `default: null`），并且当前值与该默认值匹配，则将其包含在请求中。这是工具期望的有意义的值
- **始终包含必填字段** - 即使为空，也要保留必填字段值，以便 MCP 服务器可以验证并返回适当错误消息
- **将深入验证延迟到服务器** - 在检查器客户端实现基本字段存在检查，但根据其架构依赖 MCP 服务器进行参数验证
这些指南维护了干净的参数传递和检查器客户端与 MCP 服务器之间适当的关注点分离。
## License
本项目根据 MIT License 授权 — 请参阅 [LICENSE](LICENSE) 文件了解详细信息。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器