第一次在Cursor里配MCP我就在设置界面翻了车添加了一个filesystem server命令填了npx -y modelcontextprotocol/server-filesystem结果状态栏一直显示connection failed日志也看不太懂。后来折腾了半个多小时才发现问题出在我本机默认的Node路径跟Cursor调用的环境不一致上。等彻底跑通之后回头看配置MCP本身其实不难真正难的是理解它背后那套AI如何调用外部工具的机制。这篇文章我把自己在Cursor里配置MCP的完整过程写下来包括环境准备、两种配置方式、配置文件的每个字段、值得优先尝试的现成服务、典型的踩坑排查链路以及怎么自己写一个最小可用的MCP server给正在被AI只读得懂代码、碰不到外部世界折磨的朋友做个参考。MCP的全称是Model Context Protocol中文一般叫模型上下文协议它解决的是一个很具体的问题让AI Agent能够通过一套标准化的方式去调用外部工具和数据源。Cursor是目前支持MCP做得最完整的AI编码工具之一配好之后Agent不只是帮你改代码还能去读设计稿、查数据库、操作Blender建模、跑浏览器自动化脚本——这些都是纯靠提示词没办法做到的事情。1. 为什么要在Cursor里配MCPAgent缺的不是聪明是触手1.1 没有MCP之前我是怎么被憋死的在没有MCP之前我在Cursor里做很多事都感觉很隔。举个最典型的场景我手上有一套前端项目设计稿在Figma上后端接口文档在内网Wiki里数据库在本地Docker里跑着。我想让Cursor帮我根据设计稿写一个页面组件传统做法是什么先把Figma里的色值、间距、字号一个个抄下来再把接口返回的JSON结构复制进对话最后还要把数据库表结构口头描述一遍。只要有一个步骤描述不准确AI生成的代码就是错的。这本质上不是AI笨而是它没有眼睛和手——它看不到Figma画布连不上数据库只能靠我在对话里喂二手信息。我当时试过很多变通方案用截图让AI识别像素颜色、写Python脚本去读数据库再让AI分析、把设计稿导出的CSS贴进对话里……能用都用了但每一条路都很依赖手工搬运而且每次数据结构一变整个流程就要重来一遍。直到后来我开始用MCP这些场景才真正变成AI自己去看、自己去拿我只需要告诉它去看Figma里那个页面的样式帮我对齐前端代码就够了。1.2 MCP到底干了什么事用个类比说清楚MCP的工作方式可以类比成USB-C接口以前你带了一堆设备每台设备都要一根专属线充电器上全是口。MCP做的事情是把AI调用工具这个动作标准化成同一个接口——不管工具是文件系统、数据库、设计软件还是浏览器都通过统一的协议去连接。具体到架构上MCP有三大角色模型Model、主机Host比如Cursor、服务器Server比如一个文件系统工具。Server可以跑在本地通过标准输入输出stdio通信也可以跑在远程服务器上通过HTTP或SSE通信。你只需要在Cursor里把Server的启动方式或地址告诉它Cursor就会在Agent运行的时候把Server提供的工具列表加载进来。当Agent决定需要某个能力时它会直接调用对应的工具然后把返回结果当作上下文继续推理。整个过程对用户来说就是Agent多了一批可以自主决定用不用的小工具。1.3 Cursor和MCP的适配现状Cursor对MCP的支持从0.45版本前后开始逐步完善我实测下来几个关键点项目级的MCP配置放在.cursor/mcp.json里全局配置放在~/.cursor/mcp.json里设置面板里可以管理启用状态和查看工具列表Agent在对话中能够自动决定是否调用已加载的MCP工具。Cursor的MCP实现基本兼容官方SDK也就是说大部分现成的MCP server直接配置就能用。但有几个细节需要注意不同版本的Cursor对远程MCP的协议支持有差异老版本可能只支持stdio新版本才完整支持HTTP和SSE另外MCP工具加载之后不会出现在普通Edit对话里只有Agent模式才会主动调用这个后面会详细说。2. Cursor接入MCP的完整配置链路2.1 环境前置检查先把自己这边的底子打好配置MCP之前我建议你花两分钟确认三件事很多配置完连不上的问题都是从这里开始的。第一Cursor版本不能太老。MCP功能在旧版本里甚至找不到入口你可以在Cursor的Settings - About里查看版本号如果低于0.45建议先升级到最新稳定版。MCP本身迭代速度很快新版Cursor对协议的支持更完整。第二如果要用stdio类型的MCP server本机必须能正常执行相关命令。相当多的MCP server是发布在npm上的用npx就能启动所以检查Node环境很重要。我建议你在终端里跑一下node -v和npx -v确保Node版本在18以上npx能正常工作。之前我遇到的那个connection failed就是因为系统默认的npx路径和Cursor启动进程时用的PATH不一致后面用绝对路径才解决。第三远程类的MCP server需要网络能访问到目标地址并且你要提前拿到访问凭证一般是Token或者API Key。比如Figma MCP需要Figma的个人访问令牌蓝湖的MCP服务需要你在蓝湖平台生成对应的密钥。别等配置完再去翻凭证那会浪费很多时间。2.2 两种添加方式设置面板和配置文件Cursor里添加MCP server有两种方式我日常会混合使用。第一种是UI方式打开Cursor的设置面板快捷键是CtrlShiftJmacOS上是CmdShiftJ切到Features往下滚动找到MCP一栏点击 Add MCP Server。这时候会弹出一个对话框需要填三样东西Server名称、类型stdio或remote、命令或URL。填完保存后MCP server会自动开始连接状态栏会从connecting变成connected下面还会列出这个server暴露出来的工具列表。第二种是配置文件方式。在项目根目录创建.cursor/mcp.json或者编辑全局的~/.cursor/mcp.json格式是固定的JSON。我用这种方式比较多因为配置可以跟着项目走其他人clone项目之后也能复用同一套MCP配置。配置文件的完整结构长这样{ mcpServers: { my-local-server: { type: stdio, command: npx, args: [-y, your-mcp-package], env: { API_TOKEN: your-token } }, my-remote-server: { type: http, url: https://example.com/mcp, headers: { Authorization: Bearer your-token } } } }两种方式的作用范围不同UI方式添加的server全局生效配置文件方式添加的server默认只对当前项目生效。一般来说我自己常用的filesystem、github这类通用工具放在全局跟具体项目强绑定的工具比如某个项目的专用脚本放在项目级配置文件里。2.3 验证配置成功的标准方法配置完MCP之后怎么判断它真的能用了我总结了三个检查步骤。第一步看连接状态。在设置面板的MCP区域每个server会显示连接状态。connected表示进程启动成功、协议握手完成failed表示启动或通信有问题点进日志能看具体报错。注意有些stdio server启动很慢状态可能会在connecting停留几秒这是正常的不用着急。第二步看工具列表。连接成功的server下方会列出它提供的所有工具。比如filesystem server会有一堆read_file、write_file、list_directory之类的工具。如果工具列表为空说明server本身没暴露任何工具或者版本不兼容。第三步也是最关键的新建一个Agent对话看Agent能不能识别并调用这些工具。注意必须是新开的对话旧对话不会自动加载新配置的MCP工具。在对话里你可以直接问Agent你现在有哪些MCP工具可以用或者描述一个具体任务观察Agent是否会主动使用MCP工具来执行。3. 配置文件的字段拆解与典型示例3.1 每个字段是什么含义配置文件里每个字段都有明确含义我挨个拆一下。最顶层是固定的mcpServers键不能改名。它的值是一个对象每个键都是一个server的名称——这个名字相当于给server起的一个IDAgent调用工具时会在内部通过这个名字来标识来源所以最好起得语义化一点比如figma、local-fs。每个server对象支持这些字段字段说明适用类型type连接类型stdio或http/sse全部command要执行的命令例如npx、pythonstdioargs传给命令的参数数组stdioenv设置给子进程的环境变量stdiourl远程MCP服务的HTTP地址http/sseheaders请求时附加的HTTP头通常放Tokenhttp/sse值得多说一句的是env。很多MCP server需要API密钥才能运行比如GitHub MCP需要GITHUB_PERSONAL_ACCESS_TOKEN。把这个Token直接写在配置文件里虽然方便但如果项目会共享给别人建议在.cursor/mcp.json里引用环境变量Cursor支持类似${ENV_VAR}的变量替换方式这样就不会把密钥写进代码库了。3.2 本地stdio服务器的标准写法filesystemfilesystem是我觉得最适合入门的一个MCP server它的功能很简单——让AI能够读取和写入你指定目录里的文件。配置方法如下{ mcpServers: { local-fs: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/me/projects, /Users/me/notes ] } } }这里的重点在于modelcontextprotocol/server-filesystem后面跟的路径就是AI可以访问的目录白名单。你给它几个目录它就能访问几个目录这样不容易出现AI乱读你全盘文件的情况。我第一次配置的时候填了个/结果Agent联调的时候读了一堆无关的系统文件不仅浪费token还拖慢响应速度后来改成只放项目目录和相关文档目录体验好了很多。配置完成后你在Agent对话里说帮我看看/Users/me/projects/test目录下有哪些文件把最大的三个文件列出来Agent就会自动调用list_directory和get_file_info这些工具来完成。3.3 远程HTTP服务器的配置Figma和蓝湖场景远程MCP server的配置思路不太一样它不需要在本地启动进程而是通过URL去连接一个已经在运行的服务。这种模式很适合那些数据不在本地的场景。以Figma为例。Figma官方提供了一个MCP server可以让AI读取特定Figma文件里的图层、样式、坐标信息然后帮你生成前端代码。配置方法是{ mcpServers: { figma: { url: https://mcp.figma.com/mcp, type: http, headers: { Authorization: Bearer figd_your_personal_access_token } } } }那个token需要去Figma的Settings - Security - Personal access tokens里生成。配置好之后你在对话里发一个Figma文件的链接告诉Agent看一下这个设计的配色和间距帮我生成对应的Tailwind类Agent就能自己去读设计稿数据。这个场景我实际用过几次虽然不能做到像素级的对照但生成的结果结构完整度明显比我口述设计稿的方式高一个档次。蓝湖的MCP服务也是类似思路。蓝湖是国内团队常用的设计协作平台它提供的MCP服务主要用来读取设计标注、切图信息和代码片段。配置的时候把蓝湖文档里给出的远程MCP地址填进url再按它的要求配置Token即可。因为蓝湖的接入方式偶尔会调整最稳妥的做法是去蓝湖开放平台的最新文档里拿配置参数。4. 值得优先尝试的几个现成MCP服务4.1 Blender MCP用自然语言驱动建模Blender MCP是社区里做得比较早也比较成熟的MCP server之一它让我意识到MCP的想象空间远不止文件读写。它的原理是在Blender里跑一个插件插件启动一个MCP server然后Cursor里的Agent通过MCP协议跟这个server通信从而操作Blender内部的对象、材质、相机、渲染等。配置分两步第一步在Blender里安装插件。把blender-mcp的插件代码放到Blender的插件目录在Edit - Preferences - Add-ons里启用然后运行插件它会启动一个Python服务的MCP端点。第二步在Cursor的mcp.json里配置{ mcpServers: { blender: { command: python, args: [/absolute/path/to/blender_mcp_server.py], env: {} } } }注意这里的python路径要用绝对路径否则Cursor可能找不到你系统里装的那个Python解释器。配置好之后你可以用自然语言让Agent调整物体位置、修改材质颜色、甚至生成基础几何体。我试着让Agent把场景里的立方体改成金属质感、再复制三个排成一行它确实能一步步调用工具完成。这个玩意的上限取决于Blender插件的工具覆盖范围但作为AI进入3D软件的入口方向感是非常明确的。4.2 浏览器自动化类MCP让AI真的去操作网页另一个我特别喜欢的方向是浏览器自动化。市面上比较常用的是puppeteer的MCP实现例如modelcontextprotocol/server-puppeteer它把无头浏览器封装成了MCP工具AI可以自己去打开网页、点击按钮、读取页面内容、截图。配置方式同样简单{ mcpServers: { puppeteer: { command: npx, args: [-y, modelcontextprotocol/server-puppeteer] } } }我实际用过的场景是调试一个前端页面让Agent打开本地开发服务器地址把页面上某个按钮的文案截图下来再跟接口返回的数据做对比。这在以前我得自己打开浏览器、按F12、找半天元素现在直接告诉Agent任务它自己就去操作浏览器了。当然无头浏览器在复杂交互页面上偶尔会卡住但处理一般的DOM检查和页面信息提取非常够用。4.3 数据库、搜索与日常工具的组合思路除了上面这些我把几类值得优先尝试的MCP工具按场景列一下你可以根据自己的开发习惯选场景推荐MCP典型用途数据库操作sqlite / postgres MCP让AI直接查表结构、写SQL、读取结果代码仓库github MCP读Issue、看PR、审代码搜索与检索官方参考搜索类MCP让AI搜索最新文档、避免知识过期本地知识库向量库/文件检索MCP让AI检索本地笔记、技术文档运维工具kubectl/服务器类MCP让AI查看日志、检查服务状态一个经验是MCP工具不是越多越好。每个工具的schedule都会占用上下文工具数量一多Agent的推理速度和准确率都会受影响。我的习惯是日常只加载两三个必须的server用到哪个临时开哪个。5. 配置MCP过程中最常见的坑与排查链路5.1 五类典型报错的完整排查思路MCP配置出问题的时候最怕的是无头苍蝇一样乱试。我根据自己的踩坑经历整理了一个排查思路强烈建议你按照这个顺序走。第一个最常见的是Connection failed。先看server的日志输出在Cursor设置面板的MCP区域点对应server的log能看到启动命令的完整输出。stdio类型的话常见原因是命令本身不存在、参数写错、或者启动路径不对。这时候在终端手动执行一遍配置文件里的command和args如果本地也报错问题基本就在命令本身如果本地能跑通但Cursor里失败大概率是环境变量PATH差异改用命令的绝对路径可以解决。第二个是工具列表为空。这可能是因为server进程启动了但没成功注册工具通常是因为server版本和Cursor的MCP协议实现不兼容。解决办法是先确认server支持的标准MCP协议版本再更新Cursor或换用兼容版本的server。还有一种情况是server需要额外的初始化参数才能暴露工具需要去server的文档里查环境变量配置。第三个是Agent明明加载了工具却不用它。我刚开始也遇到这种情况perplexity后配置好了server工具列表也显示了但Agent就是不用。后来发现原因在于Agent需要在对话上下文中感受到这个工具能帮助完成任务才会调用。你直接问它有什么工具它可能回答得很模糊但当你提出一个具体任务时它就会去调用合适的工具。如果还是不用可以尝试在对话里明确提示你可以使用MCP工具来完成这个任务。第四个是远程MCP连接超时。HTTP/SSE类型的server如果连不上先检查URL能否在浏览器里访问、证书是否有效、Token是否过期。有些远程server有防火墙或者IP白名单你可能需要把出口IP加进去。实在排查不出来用curl模拟一下同样的请求带上headers看返回是不是正常的MCP初始化响应。第五个是权限和缓存问题。stdio server可能因为权限不足无法访问某些目录导致工具运行时返回错误。另外Cursor对MCP配置有时候会有缓存改了配置文件但状态不刷新重启Cursor基本上能解决大部分玄学问题。5.2 为什么我配好了工具Agent却看不见这个问题我前后困惑了挺久后来搞明白了主要有三个原因。第一个原因是开新对话。MCP工具是Agent启动时加载的旧对话在启动时没有这些工具信息所以即使你现在配置好了回到旧对话里问它你能用MCP吗它大概率会告诉你我没有MCP工具。这不是配置失败只要新开一个对话Agent就会加载新配置。第二个原因是Agent模式。Cursor的普通Edit模式下AI只做文本编辑不会调用外部工具。只有切到Agent模式它才会主动规划任务、判断是否需要调用MCP工具。如果你在普通对话里问你能不能读取Figma设计稿它当然说不能因为它根本不是在Agent模式下运行的。第三个原因是server被禁用了。Cursor设置面板的MCP区域里每个server都有一个开关还有类似权限控制的能力可以让你设置哪些工具被允许在哪些项目里使用。如果开关是关的工具就不会被加载。有个小技巧是Cursor的MCP面板里可以看到工具级别的enable/disable状态某些server的工具默认可能是disabled需要手动打开。5.3 日志、状态流转和玄学重启最后聊几个实操细节。MCP server的状态流转一般是idle - connecting - connected - loading tools - ready其中loading tools阶段会短暂停留如果一直卡在这里大概率是server响应超时。Cursor在MCP server启动后不会自动拉工具通常要等Agent真正需要用工具时才握手——所以你可能会发现状态显示connected但工具列表却是空的等Agent调用时工具才被载入这种机制要注意一下。如果实在排查不出来先别急着卸载重装试试这么几招停掉旧的server连接、删掉重复配置、重启Cursor、清一下项目缓存。大部分配置问题都是环境残留导致的重启一次基本能解决。6. 自己写一个最小可用的MCP server6.1 用Python快速实现本地代码仓库工具官方SDK让手写MCP server变得相当简单。以Python为例mcp库提供了FastMCP类写起来很顺手。首先安装依赖pip install mcp然后写一个脚本比如local_mcp.pyfrom mcp.server.fastmcp import FastMCP mcp FastMCP(my-local-tools) mcp.tool() def get_repo_summary() - str: 返回当前仓库的基本信息包括文件和目录数量。 import os entries os.listdir(.) file_count sum(1 for e in entries if os.path.isfile(e)) return f当前目录共有 {len(entries)} 个条目其中 {file_count} 个是文件。 if __name__ __main__: mcp.run()这个脚本在本地启动了一个stdio类型的MCP server暴露了一个名为get_repo_summary的工具。接下来在Cursor的.cursor/mcp.json里配置{ mcpServers: { my-local-tools: { command: python, args: [/absolute/path/to/local_mcp.py], env: {} } } }新建一个Agent对话输入用你的工具看一下当前仓库的结构你会看到Agent调用了get_repo_summary并把返回结果整理成回答。6.2 把已有脚本快速包装成MCP工具这个模式的价值在于你可以把自己平时写的Python工具脚本全部转成MCP工具然后让Agent在需要时直接调用。比如我之前写了一个PDF批量合并脚本参数是两个目录和一个输出路径原来只能手动在终端里运行。我把它改成了MCP工具函数接收源目录和输出路径内部调用原来的逻辑几分钟就接入了Cursor。改造的时候有两点建议一是函数参数和返回值尽量用基础的JSON序列化类型字符串、数字、数组、字典因为MCP协议传输的是JSON复杂对象要自己序列化二是给每个函数写清楚的docstring尤其是函数用途和参数含义因为Agent在决定是否调用工具时主要靠函数名和docstring来理解工具能力。我见过很多人写了工具却忘了写docstring结果Agent完全不知道怎么用。6.3 MCP和其他能力的关系Agent Skill、Function Calling的区别既然聊到这里顺便把MCP和几个容易混淆的概念一次性说清楚。Function Calling是模型API层面的一种能力指的是模型在生成回复时可以输出一个结构化调用请求让开发者的应用去执行某个函数。它是模型与宿主应用之间的约定没有统一的传输协议。MCP则是在这之上的一层标准化协议解决的是工具如何被发现、如何被描述、如何被调用的问题。它让同一个工具可以被不同的AI应用复用——Cursor能用其他支持MCP的应用也能用。Agent Skill是Cursor里的一种机制主要用于定义Agent的工作流和指令本质上是把提示词、脚本和工具调用组合成一套可复用的技能。它和MCP的区别在于Skill更偏向教Agent怎么按步骤做一件事MCP更偏向给Agent提供它做事时能使用的工具。两者可以搭配使用用Skill定义流程用MCP提供能力。说到我个人的体会MCP最吸引我的地方不是某一个具体server而是它的协议化思路让你积累的工具资产可以持续复用。今天写的一个内部脚本明天接上另一个支持MCP的应用几乎不需要改动。最后再分享一个小技巧如果你发现某个MCP server在Cursor里表现不稳定可以先在官方的MCP Inspector工具里单独调试它确认它本身没问题再回到Cursor里排查配置。这样能省掉很多来回折腾的时间。