这个教程解决什么问题

Cursor 自带的武器只有读写代码和跑终端命令。接入 MCP（Model Context Protocol）之后，Agent 能抓网页、操作浏览器、在限定目录里读写文件、查 GitHub 仓库状态。MCP 是 Anthropic 在 2024 年 11 月开放的标准协议，现已被多款主流 AI 编程工具支持。这篇带你理解概念、挑对起步 server、写对配置文件、验证工具真的被调用，并避开 Windows 上最出名的那几个坑。

环境与版本

项要求
Cursor已安装登录；版本在 Help → About 查看【待补：你的版本号】
Node.js18 或更高（npx 拉起 stdio server 用）
Python3.10+（uvx 运行 Python 系 server 用，可选）
网络首次运行需要访问 npm / PyPI 拉取依赖

没装 Node 的先装 LTS 版本；只用 Python 系 server 的话装 uv 即可，uvx 命令随 uv 一起提供，不需要手动建虚拟环境。

三分钟搞懂 MCP 概念

MCP 把”AI 能用什么”标准化成三类能力，Cursor 主要用第一类：

  • Tools：Agent 能调用的动作，如抓取一个 URL、点击页面元素。模型按需调用，调用前你可以审批；
  • Resources：server 暴露给客户端读取的数据，如文件内容、数据库 schema；
  • Prompts：server 预置的提示词模板，按需调用。

三个角色一句话讲清：Server 是提供能力的进程；Tool 是它声明出来的具体动作；Transport 是连接方式——stdio 模式由 Cursor 在本机拉起 server 进程，走标准输入输出通信；HTTP/SSE 模式连接远程服务，配置里只写一个 URL。理解了 transport，配置文件里为什么有的写 command、有的写 url，就通了。

第一步：挑起步 server

不要求多，新手建议从这张表里的两三个开始：

server安装方式能干什么注意点
filesystem（官方参考实现）npx -y @modelcontextprotocol/server-filesystem <目录>在指定目录内读写文件目录白名单机制，只给必要目录
fetchuvx mcp-server-fetch抓网页并转为 Markdown 供模型阅读需要 Python 环境走 uvx
playwrightnpx -y @playwright/mcp操控浏览器：打开页面、点击、截图首次要下载浏览器内核
github（官方）远程或本地均可查 issue、PR、仓库信息需配 GitHub 令牌到 env

这些名字都是官方或厂商维护的实现，来源可信；来路不明的第三方 server 不要接——它和你的代码跑在同一台机器上。

第二步：写配置文件

配置分两级：项目级 .cursor/mcp.json（随仓库共享，只放该项目需要的）与全局 ~/.cursor/mcp.json（Windows 在用户主目录下，跨项目通用）。文件骨架：

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/work/demo"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

需要凭证的 server 用 env 字段传入，GitHub 官方 server 的本地写法：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@github/mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的令牌"
      }
    }
  }
}

令牌在 GitHub 的开发者设置里生成，只勾选必要权限（如只读仓库内容），过期与泄露风险都更小。

第三步：启用并验证连接

保存后打开 Settings 里的 MCP 面板，点刷新，几秒到几十秒内每个 server 应显示已连接。第一次启动慢是正常的：npx 要把包拉到本地（示例：首次启动可能等 30 秒以上，发布前替换为你的实测），浏览器类 server 首次使用还要下载浏览器内核【待补：实测耗时与体积】。连不上就到终端手动跑一次命令，报错比面板直观：

# 手动能打印日志，说明命令本身没问题，问题多半出在配置或环境变量
npx -y @playwright/mcp

Windows 用户注意：stdio 型 server 在 Windows 上常见”明明装了 Node 却连不上”，原因是 Cursor 直接拉起进程时找不到 npx。解决：command 改用 cmd，把原命令包进 args：

{
  "mcpServers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp"]
    }
  }
}

第四步：在 Agent 里用起来

新开对话（Agent 模式），直接描述目标，模型会自己挑工具。三个验证用例由浅入深：

1. 用 fetch 工具抓取 https://example.com 并用中文总结页面内容
2. 在 D:/work/demo 里新建 notes 目录，把总结写进 summary.md
3. 用 playwright 打开 http://localhost:3000 ，检查登录页能否正常渲染并截图

调用发生时，聊天界面会显示工具名与参数，你确认后执行。看到工具调用的提示并拿到结果，说明链路全通了。

Cursor MCP 工具调用与授权提示界面

【待补：MCP 工具调用与授权提示截图】

常见坑与解法

坑 1：JSON 写错，面板里压根不显示

mcp.json 不支持注释和尾逗号，一个多余逗号整个文件失效。改完用编辑器的 JSON 校验过一遍，或在终端粘进 python -m json.tool 确认合法。

坑 2：uvx / npx 提示找不到命令

图形界面启动的编辑器继承的 PATH 可能与终端不同：终端里 node -v 正常、Cursor 却连不上，就是这类问题。把 Node 装到系统级路径，或用上面的 cmd /c 包装法。

坑 3：工具太多，模型乱调用

每个 server 的工具都会占用上下文并干扰模型选择，工具结果本身也会随对话一路携带、持续消耗额度。按项目裁剪：写前端的项目别挂数据库 server；暂时不用的先在面板里禁用，配置留着。

坑 4：Key 泄进 git

项目级 mcp.json 的 env 字段写了真实凭证，仓库一推全员可见。做法：凭证放全局配置或环境变量，项目级只留结构；.gitignore 和团队约定里写清楚。

坑 5：远程 server 照抄 stdio 模板

HTTP/SSE 型 server 不写 command，写 url 字段（部分还要求带认证头），照服务方文档填，别把本地命令的模板硬套上去。

高频问答

  • MCP 调用安全吗：stdio 型 server 在你本机以你的权限运行，装可信来源、filesystem 只给白名单目录、令牌最小权限，三条守住底线；
  • 和 Claude Code 的 MCP 配置通用吗：协议相同，server 本体可以直接复用，但配置文件路径和格式是各家客户端自己的约定，不能整个文件照搬；
  • 工具调用额外收费吗：工具结果会进入对话上下文，token 消耗随之上升，额度消耗速度与普通对话同规则，没有独立的计费项；
  • 连接超时怎么办：先手动运行命令确认 server 本体能起来，再看超时时间与网络代理设置，远程 server 优先检查认证头。

最终效果与验证清单

自查四条：MCP 面板里目标 server 显示已连接；对话中能看到工具被调用的提示与结果；filesystem 的可访问范围确实被限制在你给的目录里；git status 确认没有把凭证提交进仓库。全过，Cursor 就从”会写代码的编辑器”升级成”能动手干活的任务执行器”。

相关阅读