摘要MCP Inspector是官方可视化调试工具支持Server连接测试、工具调用模拟、资源浏览和协议消息查看。本文详解Inspector安装使用和常见调试场景提升MCP开发效率。MCP Inspector工具详解可视化的Server调试利器我写完第一个MCP Server后兴冲冲地配到Claude Desktop里结果Claude那边毫无反应连个报错都没有。我在终端手动运行server只看到光标闪了闪就没了。调试了快两个小时最后用MCP Inspector一连接立刻发现是工具的inputSchema写错了zod的类型定义跟实际参数对不上。从那以后Inspector成了我开发MCP Server的标配工具这篇文章把它的安装、使用和调试技巧完整讲一遍。MCP Inspector是什么MCP Inspector是官方出品的交互式调试工具专门用来测试和调试MCP Server。它跑起来是一个本地Web界面你可以在里面可视化地连接服务器、调用工具、读取资源、测试prompt还能实时查看所有JSON-RPC消息的收发记录。它的架构分两部分。MCP Inspector Client简称MCPI是一个React写的Web界面负责展示和交互。MCP Proxy简称MCPP是一个Node.js进程负责代理你的MCP Server把客户端和服务器之间的消息转发给Web界面。你操作Web界面时指令经过Proxy发给ServerServer的响应再经Proxy回传到界面。这个设计的好处是你不用关心传输层细节。不管是stdio还是Streamable HTTPInspector都能接管。安装和启动Inspector不需要单独安装直接用npx运行就行。# 基本用法后面跟启动server的命令npx modelcontextprotocol/inspectorcommand[args...]我分三种常见场景说明。场景一调试本地TypeScript server。编译好之后用node运行编译产物。npx modelcontextprotocol/inspectornodebuild/index.js场景二调试npm上发布的server包。比如官方的文件系统server。npx-ymodelcontextprotocol/inspector npx modelcontextprotocol/server-filesystem /Users/username/Desktop场景三调试Python server。用uvx运行PyPI上的包。npx modelcontextprotocol/inspector uvx mcp-server-git--repository~/code/myproject.git运行后终端会输出一行类似Inspector running at http://localhost:6274的地址。用浏览器打开这个地址就能看到调试界面。我第一次用的时候遇到了端口冲突问题。6274端口被别的程序占了Inspector没报错但页面打不开。解决办法是手动指定端口。# 设置Web界面端口npx modelcontextprotocol/inspector--port6280nodebuild/index.js# 也可以设置Proxy的端口npx modelcontextprotocol/inspector --server-port6281nodebuild/index.js界面功能详解打开Inspector的Web界面后左边是服务器连接面板右边是几个功能标签页。我按从上到下的顺序讲。服务器连接面板这个面板在最左边用来配置传输方式和连接参数。对于stdio传输你可以在这里修改启动命令和参数。比如你的server需要环境变量可以在Environment区域添加键值对。改完之后点Connect按钮重新连接。我经常用到的一个功能是切换传输方式。开发本地server时用stdio部署到服务器后用Streamable HTTP。Inspector支持直接填URL连接HTTP模式的server省得我专门写个客户端来测。连接成功后面板会显示协议版本、服务器名称和版本号、以及能力协商的结果。如果你看到能力列表里Tools、Resources、Prompts都亮着说明握手成功了。如果某项是灰的要么server没注册对应能力要么握手时能力协商出了问题。Tools标签页这是我用得最多的标签页。左边列出server注册的所有工具点一个工具名右边显示它的描述和参数schema。参数输入区会根据schema自动生成表单。比如你的工具参数定义了一个字符串类型的最小长度1表单里就是必填的文本框。如果定义了枚举值表单里就是下拉选择框。填完参数点Run Tool按钮下方会显示执行结果。我有个习惯每写完一个工具就立刻在Inspector里测一遍。传正常参数看返回对不对传空值看校验是否生效传非法类型看错误提示是否友好。这比配到Claude里再测效率高得多因为Claude那边要重启客户端Inspector这边点Reconnect就行。Inspector还支持查看工具调用的原始请求和响应。点结果区域旁边的JSON视图能看到完整的JSON-RPC消息包括method、params、result的所有字段。排查协议层面的问题特别有用。Resources标签页Resources标签页展示server提供的可读资源。每个资源会显示URI、MIME类型和描述。点击一个资源URIInspector会向server发送resources/read请求把资源内容显示出来。如果你的资源是JSON格式它会美化显示。如果是纯文本直接展示原文。这个标签页还支持订阅测试。如果server声明了resources能力且带subscribe子能力你可以点Subscribe按钮订阅某个资源的变化。之后server每次发resources/updated通知Inspector都会在通知面板里显示。我之前写过一个监控日志文件的server把日志作为resource暴露。在Inspector里订阅之后我修改了日志文件立刻在通知面板看到更新通知确认了订阅机制是通的。Prompts标签页Prompts标签页列出所有prompt模板。选中一个模板后右边显示它的参数定义。填好参数点Get Prompt按钮Inspector会发送prompts/get请求下方显示生成的消息内容。消息以对话格式展示你能看到role和content。如果是多轮对话模板所有消息都会列出来。这个功能帮我抓过一个bug。我写了一个prompt模板参数focus设为可选但模板代码里没处理focus为undefined的情况导致拼接出来的提示词里多了个undefined字符串。在Inspector里不填focus参数调用一次立刻就看到了这个问题。Notifications通知面板通知面板在界面底部实时显示server发来的所有通知消息。这里有几种常见的通知。notifications/initialized是握手完成通知。notifications/message是server的日志消息按RFC 5424的八个级别分类从debug到emergency。notifications/resources/updated是资源更新通知。notifications/tools/list_changed是工具列表变更通知。我调试时会把通知面板的日志级别调到debug这样能看到server内部所有的日志输出。前提是你的server得用SDK的logging接口发日志光用console.error写到stderr的日志Inspector也能捕获但不会按级别分类。与手动调试的对比在用Inspector之前我是怎么调试MCP Server的呢。写一个测试脚本手动构造JSON-RPC消息通过子进程的stdin发给server再读stdout解析返回。大概长这样。// 手动调试脚本极其痛苦import{spawn}fromchild_process;// 启动server子进程constchildspawn(node,[build/index.js]);// 监听stdout解析JSON-RPC响应letbuffer;child.stdout.on(data,(data){bufferdata.toString();// 按换行符分割消息constlinesbuffer.split(\n);bufferlines.pop();// 保留最后不完整的一行for(constlineoflines){if(line.trim()){constmsgJSON.parse(line);console.log(收到响应,JSON.stringify(msg,null,2));}}});// 监听stderr日志child.stderr.on(data,(data){console.log([server日志],data.toString());});// 发送initialize请求child.stdin.write(JSON.stringify({jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2025-06-18,capabilities:{},clientInfo:{name:test-client,version:1.0.0},},})\n);// 等握手完成后再发initialized通知和工具调用// ... 需要手动管理时序很容易出错这种手动调试方式的问题太多了。消息时序要自己管initialize响应没回来就发工具调用会失败。参数格式容易写错JSON里少个逗号整条消息就废了。输出解析也很烦stdout的buffer可能被截断你得自己拼。最痛苦的是没法可视化每次调用工具都要改脚本重新跑。对比维度MCP Inspector手动写脚本调试启动成本一行命令搞定要写几十行通信代码工具调用表单填参数点按钮手动构造JSON发stdin结果展示格式化显示JSON视图自己解析stdout输出消息监控自动记录所有收发消息要自己加日志协议握手自动完成initialize流程手动发请求管时序传输切换改个下拉框就行stdio和HTTP要写不同代码环境变量界面里直接填改脚本里的spawn参数结论很明确开发阶段一律用Inspector别花时间写调试脚本。手动脚本只在需要做自动化测试时才有价值。实战调试流程我总结了一套标准的调试流程每次写新server都按这个来。第一步启动Inspector连接server检查握手是否成功。看连接面板的协议版本和能力列表确认Tools、Resources、Prompts该亮的都亮了。第二步逐个测试工具。先传正常参数再传边界值最后传非法值。每个工具至少测三个case。第三步检查消息日志。在通知面板里查看工具调用的完整请求和响应确认参数传递和返回格式符合预期。第四步测试资源和prompt。读取所有资源调用所有prompt模板确认输出正确。第五步断线重连测试。点Disconnect再Connect确认server能正确处理重复初始化。第六步集成到目标客户端。Inspector里测通后再配到Claude Desktop或其他host里做最终验证。常见问题与避坑第一个坑Inspector版本太旧。MCP协议更新很快旧版Inspector可能不支持新版协议的某些特性。用npx modelcontextprotocol/inspectorlatest强制拉最新版。我有一次用了缓存的旧版Inspector连接时显示协议版本不匹配更新后就好了。第二个坑server启动失败但Inspector没报错。如果你的server代码有运行时错误启动就崩了Inspector可能只显示连接断开但不告诉你原因。解决办法是先在终端单独运行server看有没有报错确认能正常启动后再用Inspector连接。第三个坑环境变量没传进去。Inspector的连接面板里可以配环境变量但很多人没注意到。如果你的server依赖API Key之类的环境变量一定要在Environment区域填上。我之前调一个连数据库的server死活连不上最后发现是Inspector没传数据库连接串。第四个坑stdio模式下的路径问题。Inspector启动server时的工作目录可能跟你预期的不一样。如果你的server代码里用了相对路径读文件在Inspector里可能找不到文件。解决办法跟Claude Desktop一样代码里一律用绝对路径。第五个坑消息太多看不过来。复杂的server一次交互会产生大量JSON-RPC消息通知面板会刷得很快。我习惯先调到warning级别过滤掉debug日志定位到具体问题后再切回debug看细节。Inspector的消息面板支持搜索过滤善用这个功能。小结MCP Inspector是开发MCP Server必备的可视化调试工具用npx一行命令启动通过Web界面完成协议握手、工具调用、资源读取、prompt测试和消息监控。跟手动写调试脚本相比它在启动成本、操作便利性和信息展示上都有压倒性优势。标准调试流程是先Inspector验证功能再集成到目标客户端做最终测试。使用时注意保持Inspector最新版、配好环境变量、用绝对路径遇到问题先单独运行server排查。相关推荐5分钟跑通你的第一个MCP ServerPython版测试与调试MCP Inspector、单元测试、集成测试新手避坑指南MCP开发中最常见的10个错误