modelcontextprotocol/inspector

# MCP Inspector MCP inspector 是一款用于测试和调试 MCP server 的开发者工具。  ## 架构概览 MCP Inspector 由两个协同工作的主要组件组成： - **MCP Inspector Client (MCPI)**：一个基于 React 的 Web UI，提供用于测试和调试 MCP server 的交互式界面 - **MCP Proxy (MCPP)**：一个 Node.js server，充当协议桥接，通过多种传输方法（stdio、SSE、streamable-http）将 Web UI 连接到 MCP server 请注意，该代理并不是用于拦截流量的网络代理。相反，它同时充当 MCP client（连接到您的 MCP server）和 HTTP server（为 Web UI 提供服务），使得基于浏览器的交互能够与使用不同传输协议的 MCP server 进行通信。 ## 运行 Inspector ### 环境要求 - Node.js: ^22.7.5 ### 快速开始（UI 模式） 要立即通过 UI 启动并运行，只需执行以下命令： ``` npx @modelcontextprotocol/inspector ``` Server 将启动，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 server 仓库 要检查 MCP server 的实现，无需 clone 此仓库。只需使用 `npx`。例如，如果您的 server 构建在 `build/index.js`： ``` npx @modelcontextprotocol/inspector node build/index.js ``` 您可以将参数和环境变量传递给您的 MCP server。参数将直接传递给您的 server，而环境变量可以使用 `-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 # 使用 -- 将 inspector 标志与 server 参数分隔开 npx @modelcontextprotocol/inspector -e key=$VALUE -- node build/index.js -e server-flag ``` Inspector 会同时运行 MCP Inspector (MCPI) client UI（默认端口 6274）和 MCP Proxy (MCPP) server（默认端口 6277）。在浏览器中打开 MCPI client UI 即可使用 inspector。（这些端口分别源自 MCPI 和 MCPP 的 T9 拨号盘映射，作为助记符）。您可以根据需要自定义端口： ``` 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)。 ### Server 文件导出 MCP Inspector 提供了便捷的按钮，用于导出 server 启动配置，以便在 Cursor、Claude Code 或 Inspector 的 CLI 等客户端中使用。该文件通常称为 `mcp.json`。 - **Server Entry** - 将单个 server 配置条目复制到剪贴板。您可以将其添加到 `mcp.json` 文件的 `mcpServers` 对象中，并使用您喜欢的 server 名称。 **STDIO transport 示例：** { "command": "node", "args": ["build/index.js", "--debug"], "env": { "API_KEY": "your-api-key", "DEBUG": "true" } } **SSE transport 示例：** { "type": "sse", "url": "http://localhost:3000/events", "note": "For SSE connections, add this URL directly in Client" } **Streamable HTTP transport 示例：** { "type": "streamable-http", "url": "http://localhost:3000/mcp", "note": "For Streamable HTTP connections, add this URL directly in your MCP Client" } - **Servers File** - 将完整的 MCP 配置文件结构复制到剪贴板，您当前的 server 配置会被添加为 `default-server`。这可以直接保存为 `mcp.json`。 **STDIO transport 示例：** { "mcpServers": { "default-server": { "command": "node", "args": ["build/index.js", "--debug"], "env": { "API_KEY": "your-api-key", "DEBUG": "true" } } } } **SSE transport 示例：** { "mcpServers": { "default-server": { "type": "sse", "url": "http://localhost:3000/events", "note": "For SSE connections, add this URL directly in Client" } } } **Streamable HTTP transport 示例：** { "mcpServers": { "default-server": { "type": "streamable-http", "url": "http://localhost:3000/mcp", "note": "For Streamable HTTP connections, add this URL directly in your MCP Client" } } } 这些按钮会在您配置好 server 设置后出现在 Inspector UI 中，方便您保存和重用配置。 对于 SSE 和 Streamable HTTP transport 连接，Inspector 为这两个按钮提供了类似的功能。“Server Entry”按钮复制可添加到现有配置文件中的配置，而“Servers File”按钮则创建一个包含 URL 的完整配置文件，可直接在客户端中使用。 您可以将 Server Entry 粘贴到现有 `mcp.json` 文件中您选定的 server 名称下，或使用完整的 Servers File 内容创建一个新的配置文件。 ### 身份验证 Inspector 支持 SSE 连接的 Bearer token 身份验证。在连接到 MCP server 时，在 UI 中输入您的 token，它将被包含在 Authorization header 中。您可以使用侧边栏中的输入字段覆盖 header 名称。 ### 安全注意事项 MCP Inspector 包含一个代理 server，可以运行并与本地 MCP 进程通信。该代理 server 不应暴露给不受信任的网络，因为它拥有生成（spawn）本地进程的权限，并且可以连接到任何指定的 MCP server。 #### 身份验证 MCP Inspector 代理 server 默认需要身份验证。当启动 server 时，会生成一个随机的 session token 并打印到控制台： ``` 🔑 Session token: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4 🔗 Open inspector with token pre-filled: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4 ``` 此 token 必须作为 Bearer token 包含在发往 server 的所有请求的 Authorization header 中。Inspector 将自动打开您的浏览器，并在 URL 中预填充该 token。 **自动打开浏览器** - 当启用身份验证时，Inspector 现在会自动打开您的浏览器，并在 URL 中预填充 token。 **替代方案：手动配置** - 如果您已经打开了 inspector： 1. 点击侧边栏中的“Configuration”按钮 2. 找到“Proxy Session Token”并输入代理控制台中显示的 token 3. 点击“Save”以应用配置 Token 将保存在浏览器的本地存储中以供将来使用。 如果您需要禁用身份验证（不推荐），可以设置 `DANGEROUSLY_OMIT_AUTH` 环境变量： ``` 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) 您也可以在启动 server 时通过 `MCP_PROXY_AUTH_TOKEN` 环境变量设置 token： ``` MCP_PROXY_AUTH_TOKEN=$(openssl rand -hex 32) npm start ``` #### 仅本地绑定 默认情况下，MCP Inspector 代理 server 和 client 仅绑定到 `localhost`，以防止网络访问。这确保了它们无法从网络上的其他设备访问。如果您出于开发目的需要绑定到所有接口，可以使用 `HOST` 环境变量覆盖此设置： ``` HOST=0.0.0.0 npm start ``` **警告：** 仅在受信任的网络环境中绑定到所有接口，因为这会暴露代理 server 执行本地进程的能力，并使这两个服务面临网络访问风险。 #### DNS Rebinding 防护 为了防止 DNS rebinding 攻击，MCP Inspector 会验证传入请求的 `Origin` header。默认情况下，只允许来自 client origin 的请求（如果设置了 `CLIENT_PORT` 则遵循该设置，否则默认为端口 6274）。您可以通过设置 `ALLOWED_ORIGINS` 环境变量（逗号分隔列表）来配置额外的允许 origins： ``` ALLOWED_ORIGINS=http://localhost:6274,http://localhost:8000 npm start ``` ### 配置 MCP Inspector 支持以下配置设置。要更改它们，请点击 MCP Inspector UI 中的 `Configuration` 按钮： | 设置 | 描述 | 默认值 | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `MCP_SERVER_REQUEST_TIMEOUT` | Client 端超时时间（毫秒）- 如果在此时间内未收到响应，Inspector 将取消请求。注意：server 可能有自己的超时设置 | 300000 | | `MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS` | 收到进度通知时重置超时时间 | true | | `MCP_REQUEST_MAX_TOTAL_TIMEOUT` | 发送到 MCP server 的请求的最大总超时时间（毫秒）（与进度通知配合使用） | 60000 | | `MCP_PROXY_FULL_ADDRESS` | 如果您在非默认地址上运行 MCP Inspector Proxy，请设置此项。示例：http://10.1.1.22:5577 | "" | | `MCP_AUTO_OPEN_ENABLED` | 启用 inspector 启动时自动打开浏览器（适用于启用身份验证的情况）。仅作为环境变量，不可在浏览器中配置。 | true | **关于超时的说明：** 上述超时设置控制 Inspector（作为 MCP client）何时取消请求。这些设置独立于任何 server 端的超时。例如，如果 server 工具有 10 分钟的超时时间，但 Inspector 的超时设置为 30 秒，Inspector 将在 30 秒后取消请求。相反，如果 Inspector 的超时时间为 10 分钟，但 server 在 30 秒后超时，您将收到 server 的超时错误。对于需要用户交互（如 elicitation）或长时间运行的操作的工具，请确保适当设置 Inspector 的超时时间。 这些设置可以通过 UI 实时调整，并将在会话之间持久保存。 Inspector 还支持配置文件来存储不同 MCP server 的设置。这在处理多个 server 或复杂配置时非常有用： ``` npx @modelcontextprotocol/inspector --config path/to/config.json --server everything ``` Server 配置文件示例： ``` { "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 (Server-Sent Events)：** ``` { "mcpServers": { "my-sse-server": { "type": "sse", "url": "http://localhost:3000/sse" } } } ``` **Streamable HTTP：** ``` { "mcpServers": { "my-http-server": { "type": "streamable-http", "url": "http://localhost:3000/mcp" } } } ``` #### 默认 Server 选择 如果您的配置符合以下条件，您可以在不指定 server 名称的情况下启动 inspector： 1. **单个 server** - 自动选择： ``` # 如果 "my-server" 是唯一的一个，则自动使用它 npx @modelcontextprotocol/inspector --config mcp.json ``` 2. **名为 "default-server" 的 server** - 自动选择： ``` { "mcpServers": { "default-server": { "command": "npx", "args": ["@modelcontextprotocol/server-everything"] }, "other-server": { "command": "node", "args": ["other.js"] } } } ``` 您也可以通过 query params 设置初始 `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 ``` 您还可以通过 query params 设置初始配置设置，例如： ``` 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 ``` 请注意，如果同时设置了 query param 和相应的 localStorage 项，query param 将优先。 ### 从本仓库 如果您正在开发 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 ``` 生产模式： ``` npm run build npm start ``` ### CLI 模式 CLI 模式允许从命令行与 MCP server 进行程序化交互，非常适合脚本编写、自动化以及与编码助手集成。这为 MCP server 开发创建了高效的反馈循环。 ``` 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 server（默认为 SSE transport） npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com # 连接到远程 MCP server（使用 Streamable HTTP transport） npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --method tools/list # 连接到远程 MCP server（使用自定义 headers） npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --method tools/list --header "X-API-Key: your-api-key" # 在远程 server 上调用工具 npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --method tools/call --tool-name remotetool --tool-arg param=value # 列出远程 server 的资源 npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --method resources/list ``` ### UI 模式 vs CLI 模式：何时使用 | 使用场景 | UI 模式 | CLI 模式 | | ------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Server 开发** | 用于在开发过程中进行交互式测试和调试的可视化界面 | 可编写脚本的命令，用于快速测试和持续集成；与 Cursor 等 AI 编码助手创建反馈循环以实现快速开发 | | **资源探索** | 带有分层导航和 JSON 可视化的交互式浏览器 | 用于自动化和脚本编写的程序化列出和读取 | | **工具测试** | 基于表单的参数输入，带有实时响应可视化 | 命令行工具执行，带有 JSON 输出，用于脚本编写 | | **Prompt 工程** | 带有流式响应和可视化比较的交互式采样 | 批量处理 prompt，输出机器可读的内容 | | **调试** | 请求历史、可视化错误和实时通知 | 直接的 JSON 输出，用于日志分析及与其他工具集成 | | **自动化** | 不适用 | 非常适合 CI/CD pipeline、批处理以及与编码助手集成 | | **学习 MCP** | 丰富的可视化界面帮助新用户理解 server 能力 | 简化的命令，用于针对性学习特定 endpoints | ## 工具输入验证指南 在 Inspector 中实现或修改工具输入参数处理时： - **省略具有空值的可选字段** - 在处理表单输入时，省略可选参数的空字符串或 null 值，除非字段在 schema 中具有与当前值匹配的显式默认值 - **保留显式默认值** - 如果字段 schema 包含显式默认值（例如 `default: null`且当前值与该默认值匹配，请在请求中包含它。这是工具期望的有意义的值 - **始终包含必填字段** - 即使必填字段为空，也要保留其值，以便让 MCP server 进行验证并返回适当的错误消息 - **将深度验证推迟到 server** - 在 Inspector client 中实施基本的字段存在性检查，但依赖 MCP server 根据 schema 进行参数验证 这些指南保持了清晰的参数传递以及 Inspector client 和 MCP server 之间合理的关注点分离。 ## 许可证 本项目基于 MIT 许可证授权——详情请参阅 [LICENSE](LICENSE) 文件。

标签：Docker, GNU通用公共许可证, Inspector, LLM 工具, MCP, MCP 服务器, MITM代理, Node.js, React, SSE, Stdio, Syscalls, TCP SYN 扫描, Web UI, 代理服务, 内核驱动, 前端界面, 协议桥接, 可视化测试工具, 威胁情报, 安全防御评估, 开发者工具, 接口调试, 模型上下文协议, 网络协议, 自动化攻击, 请求拦截