Claude Code / Cursor 通用 MCP 配置教程

MCP 配置的本质，就是写一段 JSON 告诉你的编辑器”用什么命令、传什么参数、带什么环境变量去启动一个外部服务”，让 AI 助手能调用文件系统、数据库、浏览器等外部能力。 不管是 Claude Code 还是 Cursor，配置的字段几乎一模一样，学会一处，处处通用。

这篇带你做到：搞清配置文件放在哪、两种连接方式（stdio / SSE）分别怎么填、装一个最常用的示例 server，并验证它真的连上了。先理解机制再抄配置，比死记参数靠谱得多——因为参数会变，机制不变。

如果你还不清楚 MCP 到底是什么协议，可以先看 MCP 协议是什么（规划中） 补一下背景。

原理：MCP 配置在做什么

MCP（Model Context Protocol）是一套标准协议，规定了”AI 客户端”和”能力提供方（server）“之间怎么对话。你的编辑器是客户端，文件系统插件、数据库连接器、浏览器自动化工具是server。

配置文件的作用，就是给客户端一张”server 清单”。客户端启动时读这张清单，按上面写的方式把每个 server 拉起来、握手、列出它提供的工具，然后 AI 在对话里就能调用这些工具了。

理解这一点很关键：MCP 配置不是在配置 AI，而是在配置”怎么启动一个进程或连一个地址”。所以核心字段永远是这几样——用什么命令、传什么参数、带什么环境变量、或者连哪个 URL。

两种连接方式：stdio 与 SSE

MCP server 主要有两种跑法，配置写法不同，先分清：

连接方式	适用场景	配置核心字段	通俗理解
stdio	server 在本机以子进程运行（最常见）	command + args + env	客户端在本地”开一个程序”，用标准输入输出对话
SSE / HTTP	server 是一个远程/常驻的网络服务	url（有时加 headers）	客户端去”连一个网址”，用 HTTP 流对话

绝大多数本地 server（文件系统、Git、SQLite 等）都是 stdio：客户端用 npx、uvx、python 这类命令把它当子进程启动。SSE/HTTP 适合远程托管的 server，比如团队共享的一个服务，你只需要填它的地址。

判断口诀：装在本机、随用随启的用 stdio；连别人部署好的网络服务用 SSE。 拿不准时优先 stdio，它最通用。

配置文件放在哪

两个工具的配置文件位置不同，但都支持”全局”和”项目级”两层。具体文件名和路径以官方文档为准（不同版本可能微调），这里给你定位思路：

Claude Code

• 用命令行管理最稳：直接 claude mcp add 系列命令增删 server，它会帮你写进配置，避免手抖写坏 JSON。
• 也支持项目级配置文件（放在项目根目录），团队成员共享同一套 server。
• 全局配置则对所有项目生效。

Cursor

• 在设置里有专门的 MCP 面板，可视化添加，底层是一个 JSON 配置文件。
• 同样区分全局（用户级）和项目级（放在项目目录下的配置文件里）。

通用原则：只在当前项目用的 server 放项目级，跨项目都要用的（如文件系统、Git）放全局。 项目级配置还能跟着仓库提交，团队开箱即用。

通用配置：一个 stdio server 的最小写法

不管哪个工具，stdio server 的 JSON 结构都是这个骨架（字段名两家基本一致）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": {
        "SOME_TOKEN": "你的密钥"
      }
    }
  }
}

逐字段拆解：

• command：启动 server 的可执行命令。Node 系常用 npx，Python 系常用 uvx 或 python。
• args：命令的参数数组，按顺序排。上例里 -y 让 npx 免确认，后面是包名和该 server 需要的参数（这里是允许访问的目录）。
• env：环境变量，通常放 API key、token 这类敏感信息。别把密钥硬写进会提交的项目配置里，能用环境变量引用就引用。

SSE/HTTP server 则简单得多，把 command/args 换成 url：

{
  "mcpServers": {
    "remote-tool": {
      "url": "https://your-server.example.com/sse"
    }
  }
}

实操：装一个示例 server

我们用最经典的文件系统 server 练手——它让 AI 能读写你指定目录里的文件，几乎人人会用到。

第一步：确认前置环境。 stdio server 多数靠 Node 或 Python 启动。装 Node 系 server 需要本机有 Node（npx 随 Node 一起来）；装 Python 系 server 需要 uv/uvx。先在终端确认对应命令能跑通。

第二步：加配置。

• Claude Code 推荐用命令：claude mcp add 后按提示填 server 名、command、args。它会自动写进配置文件，最不容易出错。
• Cursor 在 MCP 设置面板点”添加”，把上面的 JSON 骨架填进去；或直接编辑项目里的 MCP 配置文件。

第三步：把目录参数改成你自己的项目路径，比如 args 最后一项填你真实的工程目录，server 才有权限读写它。

第四步：重载。 改完配置一般要让客户端重新加载 MCP（重启编辑器，或在 MCP 面板手动刷新），server 才会被拉起。

想了解还有哪些值得装的 server 以及推荐清单，可以看 MCP 推荐必装清单（规划中）。

怎么验证连接成功

配完别急着用，先确认它真连上了：

1. 看 server 列表/状态。Claude Code 用 claude mcp list 看已配置的 server 及连接状态；Cursor 在 MCP 设置面板看每个 server 的状态指示（绿灯/已连接即正常）。
2. 看工具是否出现。连接成功后，该 server 提供的工具会被客户端识别。可以在对话里让 AI”列出你现在能用的 MCP 工具”，能列出文件系统相关操作就说明通了。
3. 跑一个真实调用。让 AI”读一下当前项目里的 README 文件”，它能正确读到内容，就证明端到端打通了。

只看到”已添加”不等于”已连接”——一定要让它真的列出工具或完成一次调用，才算验证通过。

常见坑与排查

现象	常见原因	解法
server 一直连不上 / 红灯	command 在系统里找不到（如没装 Node/uv）	在终端单独跑一遍该命令确认能执行，再回填
改了配置没生效	客户端没重载 MCP	重启编辑器或在面板手动刷新
JSON 报错、整个 MCP 都挂	手写 JSON 漏逗号/多逗号/引号不对	用编辑器的 JSON 校验，或改用 claude mcp add 命令写
server 启动但调用报错	缺 env 里的 token，或路径参数没权限	补全环境变量，确认目录参数指向真实可访问路径
远程 SSE server 连不上	url 写错或需要鉴权 header	核对地址，按 server 要求补 headers 鉴权

关于报错的更系统排查，特别是 Claude Code 这边，可以参考 Claude Code MCP 报错排查（规划中）。

常见问题

Claude Code 和 Cursor 的 MCP 配置能通用吗？

字段几乎完全通用——command、args、env、url 这套写法是 MCP 协议规定的。差别只在配置文件的位置和管理方式：Claude Code 偏命令行，Cursor 偏可视化面板。理解了字段含义，两边都能配。

stdio 和 SSE 我该选哪个？

看 server 部署在哪。本机随用随启的本地 server 选 stdio（文件系统、Git、数据库连接器基本都是）；连远程常驻的网络服务选 SSE/HTTP。日常个人开发，你接触的绝大多数是 stdio。

配置里的 env 密钥会泄露吗？

如果你把密钥明文写进会提交进 Git 的项目级配置，就有泄露风险。建议放全局配置或用环境变量引用，并把含密钥的配置文件加进 .gitignore，别跟着代码仓库一起推上去。

为什么我加了 server 却没法用？

最常见是”加了但没连上”。先确认状态是已连接（不是仅已添加），再确认客户端重载过 MCP，最后让 AI 列一次工具验证。具体启动命令、参数和支持的字段以官方文档为准，版本更新可能有调整。

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。