MCP Inspector 实用指南：Python MCP 服务器连接与工具调用测试一步到位
【免费下载链接】inspectorDeterministic testing tools for MCP servers项目地址: https://gitcode.com/gh_mirrors/inspector1/inspector
做 Python MCP 调试，最怕连接一直转圈、工具报错却看不到任何报文。MCP Inspector 是 MCP 官方出品的可视化调试客户端，一条 npx 命令就能把 MCP 服务器连接、工具调用测试与请求监控收进同一块界面。
能力速览
一句话概括：它是 MCP 协议的官方调试客户端，一个包内含 web、CLI、TUI 和实验性 mcpdo 四种形态。用得最多的是 web 形态：Node 后端 + React SPA，支持 stdio、SSE、Streamable HTTP 三种 MCP 服务器连接方式，内置 Bearer Token 与 OAuth 认证，可以可视化调用工具、浏览资源与提示词、查看日志和完整请求历史，Network 标签页里还有原始 JSON-RPC 报文。
从安装到首次连接
本地跑起来只需要一条命令（要求 Node ≥ 22.19）：
npx @modelcontextprotocol/inspector不想装 Node 环境就用 Docker 镜像：
docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector启动后打开http://localhost:6274。左侧连接面板要配三样东西：传输类型（stdio / SSE / HTTP）、启动命令（stdio 下如python server.py）或远程 URL，以及下方的启动参数和-e环境变量项。首次启动时目录会自动种入三个示例服务器——两个本地 stdio，一个官方远程 example server，直接点 Connect 就能先跑通整个流程。
一次完整的工具调用测试
连接后进入 Tools 标签页。左栏列出服务器暴露的全部工具及其注解（read-only、destructive 等）；点选一个，中栏按 inputSchema 渲染出参数表单，必填字段带红星。填好参数，点 Execute Tool，右栏 Results 返回 JSON 结果。
结果怎么算正常？看三件事：其一，content 数组结构是否完整；其二，结果里有没有isError: true——服务端工具内部抛的异常未必会中断调用；其三，到 Network 标签页对照请求体，确认发出去的参数按 inputSchema 转成了预期类型（表单输入都是字符串，由客户端负责转换）。另外注意左栏工具行的红/黄警示图标：出现即表示 schema 本身不被真实客户端接受（经典案例是 Go 服务器对 interface{} 字段发出裸true），展开 Schema portability 就能看到具体路径与修复建议。
让调试更高效：环境变量、超时与日志
高频用法先说环境变量。密钥不写死在启动脚本里，用-e传给 stdio 服务器：
npx @modelcontextprotocol/inspector -e API_KEY=your-key python server.py-e可重复书写；这些值默认存入操作系统钥匙串，不落配置文件明文。其余几个常用项：
- 超时：连接超时
connectionTimeout默认 30 秒；长任务用 "Run as task"（taskTtl 默认 60 秒），与单次请求超时解耦，慢任务不会拖垮整条连接。 - 日志：modern 协议连接可打每请求日志级别（默认 debug），想验证服务端静默行为就调成 off；TUI 用
LOG_LEVEL，进程崩溃时开MCP_DEBUG拿到完整堆栈。 - 网络：远程 HTTP/SSE 服务器用
--header附加固定请求头；内网代理环境遵循HTTPS_PROXY/NO_PROXY。
完整变量清单见环境变量文档，服务器配置文件格式见配置文档。
踩坑排查
连接一直转圈？状态卡在 connecting 不进 connected。最常见是 stdio 启动命令本身没跑起来——解释器路径不对、依赖没装，先手动在终端执行一遍；其次是传输类型与服务端不匹配，把 SSE 端点当成 http 连。确认握手已到达服务端后，到 Network 标签页看 initialize 响应是否完整。
工具执行返回 "Invalid input"？多半是参数类型与 inputSchema 声明不一致（字符串"2"对 number 字段），或 schema 本身含真实客户端不接受的构造。切到 Edit as JSON 直接核对将发送的载荷；若多个工具都报同类错误，问题在服务端 schema 侧，按 Schema portability 给出的路径改服务器，而不是在客户端打转。
OAuth 授权页拒绝 redirect_uri？预配置的 clientId 没注册 Inspector 的回调地址，或端口变了注册没跟上。到 Server Settings → OAuth Settings 复制当前 redirect URI（默认http://localhost:6274/oauth/callback）到授权服务器注册；动态注册的客户端可跳过这步。
跑完上面三步，一个 Python MCP 服务器的"连接 → 调用 → 验证"闭环就齐了；再配合 CLI 的--format json，还能把这套流程搬进 CI 变成断言。现在就启动npx @modelcontextprotocol/inspector，连上自带示例服务器，把第一个工具跑起来吧。
【免费下载链接】inspectorDeterministic testing tools for MCP servers项目地址: https://gitcode.com/gh_mirrors/inspector1/inspector
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
