Online MCP Inspector: Web-Based Tool for Testing & Debugging

MCP Inspector

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

架构概览

MCP Inspector 由两个协同工作的主要组件组成：

• MCP Inspector 客户端 (MCPI)：基于 React 的 Web UI，提供用于测试和调试 MCP 服务的交互式界面
• MCP Proxy (MCPP)：Node.js 服务，充当协议桥接器，通过各种传输方式（stdio、SSE、streamable-http）连接 Web UI 和 MCP 服务

请注意，代理并非用于拦截流量的网络代理。它同时充当 MCP 客户端（连接到你的 MCP 服务）和 HTTP 服务（提供 Web UI），从而支持通过浏览器与使用不同传输协议的 MCP 服务交互。

运行 Inspector

要求

• Node.js：^22.7.5

快速入门（UI 模式）

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

npx @modelcontextprotocol/inspector

服务启动后，可通过 http://localhost:6274 访问 UI。

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

Inspector 会同时运行 MCP Inspector (MCPI) 客户端 UI（默认端口为 6274）和 MCP Proxy (MCPP) 服务（默认端口为 6277）。在浏览器中打开 MCPI 客户端 UI 即可使用 Inspector。（这些端口分别根据 MCPI 和 MCPP 在 T9 键盘映射中的位置选取，便于记忆。）如有需要，你可以自定义端口：

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

有关 Inspector 用法的更多详情，请参阅 MCP 文档网站中的 Inspector 部分。有关调试帮助，请参阅调试指南。

导出服务器文件

MCP Inspector 提供便捷按钮，可导出服务器启动配置，以便在 Cursor、Claude Code 或 Inspector 命令行等客户端中使用。该文件通常名为 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"
  }
  

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

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

配置好服务器设置后，这些按钮会显示在 Inspector UI 中，方便保存和重复使用配置。

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

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

身份验证

检查器支持对 SSE 连接进行 Bearer 令牌身份验证。连接到 MCP 服务时，在界面中输入令牌，该令牌会放在 Authorization 标头中发送。你可以使用侧边栏中的输入框覆盖标头名称。

安全注意事项

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

身份验证

MCP Inspector 代理服务默认要求进行身份验证。启动服务时，系统会生成一个随机会话令牌并将其打印到控制台：

🔑 Session token: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

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

所有发往该服务的请求都必须在 Authorization 标头中包含此令牌，并将其作为 Bearer 令牌发送。检查器会自动打开浏览器，并在 URL 中预填令牌。

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

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

1. 点击侧边栏中的“Configuration”按钮
2. 找到“Proxy Session Token”，输入代理控制台中显示的令牌
3. 点击“Save”以应用配置

该令牌会保存到浏览器的本地存储中，供以后使用。

如果需要禁用身份验证（不推荐），可以设置 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"
    }
  }
}

Streamable HTTP：

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

默认服务选择

如果配置中包含以下内容，你可以在启动 Inspector 时不指定服务名称：

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

# Automatically uses "my-server" if it's the only one
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 按钮轻松生成此配置格式。

你也可以通过查询参数设置初始的 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

# 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 模式

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，便于分析日志和与其他工具集成
自动化	不适用	非常适合 CI/CD 流水线、批量处理以及与编码助手集成
学习 MCP	丰富的可视化界面有助于新用户了解服务的功能	通过简化的命令，专注学习特定端点

工具输入验证指南

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

• 省略值为空的可选字段 - 处理表单输入时，对于可选参数，应省略空字符串或 null 值；除非该字段在架构中有与当前值相同的显式默认值
• 保留显式默认值 - 如果字段架构包含显式默认值（例如 default: null），且当前值与该默认值相同，则在请求中包含该值。这是工具所期望的有效值
• 始终包含必填字段 - 即使必填字段的值为空，也要保留该值，以便 MCP 服务验证并返回相应的错误消息
• 将深度验证交由服务端处理 - 在 Inspector 客户端中实现基本的字段存在性检查，但参数验证应依据其架构交由 MCP 服务处理

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

许可证

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