【MCP 全栈教程】第 38 篇：在 Cursor 中集成 MCP Server
本系列定位：从协议原理到 Server 开发、Client 开发、再到各大平台实战集成，系统化掌握 MCP（Model Context Protocol）全栈技术体系。
本篇你将学到
- 掌握 Cursor 编辑器的 MCP 配置方式（全局配置与项目配置）
- 理解 MCP 工具如何融入 Cursor 的 AI 编程工作流
- 了解文件系统、Git、数据库等常用 MCP Server 的接入方法
- 学会将自定义 MCP Server 接入 Cursor 并完成端到端调试
- 一句话总结：Cursor 将 MCP 工具深度融入 Composer 和 Chat，让 AI 编程助手真正具备"操作工程环境"的能力。
一、Cursor 与 MCP 集成概述
Cursor 是一款基于 VS Code 内核构建的 AI 原生代码编辑器。与 VS Code 不同的是，Cursor 从设计之初就把 AI 能力作为核心功能，而非附加插件。Cursor 内置了强大的 Composer（多文件编辑）和 Chat（对话式编程）功能，MCP 的加入让这些功能可以触达代码之外的工程资源。
Cursor 对 MCP 的支持有以下特点：
| 特点 | 说明 |
|---|---|
| 原生集成 | 无需安装额外插件，设置面板内置 MCP 管理 |
| 双层配置 | 全局配置（所有项目共享）和项目配置（单个项目专属） |
| Composer 联动 | MCP 工具可在 Composer 多文件编辑中被调用 |
| Chat 联动 | MCP 工具可在 Chat 对话中被自动或手动调用 |
| Agent 模式 | Cursor 的 Agent 模式可自主编排多个 MCP 工具 |
| STDIO + HTTP | 支持本地 STDIO 和远程 Streamable HTTP 两种传输 |
二、Cursor MCP 配置方式
2.1 通过设置界面配置
Cursor 提供了图形化的 MCP 管理界面，这是最直观的配置方式：
- 打开设置：
Ctrl+Shift+P（macOS 为Cmd+Shift+P）→ 输入Cursor Settings - 切换到
Features→MCP选项卡 - 点击
Add new MCP Server按钮 - 填写 Server 信息并保存
配置表单字段说明：
| 字段 | 说明 | 示例 |
|---|---|---|
| Name | Server 逻辑名称 | filesystem |
| Type | 传输类型 | stdio或sse（HTTP） |
| Command | STDIO 模式的启动命令 | npx |
| Args | STDIO 模式的参数 | -y @modelcontextprotocol/server-filesystem /home/me/project |
| URL | HTTP 模式的端点地址 | https://api.example.com/mcp |
2.2 通过 JSON 文件配置
Cursor 的 MCP 配置也可以直接编辑 JSON 文件，适合批量管理和版本控制。
全局配置文件路径：
| 操作系统 | 路径 |
|---|---|
| macOS | ~/.cursor/mcp.json |
| Windows | %USERPROFILE%\.cursor\mcp.json |
| Linux | ~/.cursor/mcp.json |
项目级配置文件路径：
项目根目录下的.cursor/mcp.json
配置文件格式：
{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/home/me/projects"]},"github-api":{"url":"https://mcp.github.example.com/mcp","headers":{"Authorization":"Bearer your-token-here"}}}}2.3 全局配置 vs 项目配置
| 维度 | 全局配置（~/.cursor/mcp.json） | 项目配置（.cursor/mcp.json） |
|---|---|---|
| 作用范围 | 所有项目 | 当前项目 |
| 版本控制 | 不提交 | 可提交到仓库 |
| 适用场景 | 通用工具 Server | 项目专属 Server |
| 合并策略 | 项目配置覆盖同名全局配置 | 优先级更高 |
三、与 AI 编程工作流的融合
Cursor 的 AI 编程能力主要体现在三个入口：Chat、Composer 和 Agent 模式。MCP 工具可以无缝融入这三个入口。
3.1 Chat 模式中的 MCP
在 Cursor Chat 中，AI 会根据你的问题自动判断是否需要调用 MCP 工具。你也可以使用@符号显式引用某个 MCP Server：
@filesystem 帮我搜索项目中所有使用了 deprecated 标记的函数，并列出它们的调用位置@db-server 查询 users 表中最近注册的 10 个用户，并和 @filesystem 中的用户模型对比字段差异3.2 Composer 模式中的 MCP
Composer 是 Cursor 最强大的功能之一，支持多文件同时编辑。当 MCP 工具接入后，Composer 可以在生成代码前先查询外部资源：
| 场景 | MCP 工具的作用 |
|---|---|
| 重构 API 调用层 | 先用 API Server 查询最新接口定义，再生成符合规范的代码 |
| 数据库 Schema 变更 | 先用数据库 Server 查询当前表结构，再生成迁移脚本 |
| 文档同步更新 | 先用文件 Server 读取相关文档，再同步更新代码和文档 |
| 依赖升级 | 先用 fetch Server 获取最新版本信息，再批量更新 |
3.3 Agent 模式中的 MCP
Cursor 的 Agent 模式允许 AI 自主规划任务、连续执行多步操作。MCP 工具在 Agent 模式下作为"可用的动作"被自动编排：
任务：分析项目中的性能瓶颈并给出优化方案 Agent 的自动编排： Step 1: 调用 filesystem 读取核心模块代码 Step 2: 调用 code-search 搜索所有数据库查询 Step 3: 调用 db-server 执行 EXPLAIN 分析慢查询 Step 4: 调用 fetch 获取相关性能优化文档 Step 5: 综合分析，生成优化报告3.4 三种模式的 MCP 工具使用对比
| 模式 | MCP 调用方式 | 用户控制度 | 适用场景 |
|---|---|---|---|
| Chat | 自动或@引用 | 高（逐次确认） | 即时查询、问答 |
| Composer | 自动融入代码生成流程 | 中（整体确认） | 多文件重构 |
| Agent | 自主编排多工具链 | 低（设定目标后放手） | 复杂任务自动化 |
四、常用 MCP Server 推荐与配置
4.1 文件系统 Server
最基础也最常用的 Server，提供文件读写、搜索和目录浏览能力。
{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/home/me/projects/my-app"]}}}典型用途：
| 用途 | 调用示例 |
|---|---|
| 读取文件内容 | “读取 src/config.ts 的内容” |
| 搜索文件 | “搜索所有 .test.ts 文件” |
| 全文搜索 | “搜索包含 useState 的所有文件” |
| 创建文件 | “创建一个新的 utils/helper.ts” |
4.2 Git Server
将 Git 操作暴露为 MCP 工具，让 AI 可以查询提交历史、分析分支差异：
{"mcpServers":{"git":{"command":"uvx","args":["mcp-server-git","--repo","/home/me/projects/my-app"]}}}典型用途：
| 用途 | 调用示例 |
|---|---|
| 查看提交历史 | “显示最近 10 次提交的摘要” |
| 分析差异 | “对比 feature/login 和 main 分支的差异” |
| 查找作者 | “统计每位作者的提交数量” |
| 追踪变更 | “查找 auth.py 文件的修改历史” |
4.3 数据库 Server
数据库 Server 让 AI 可以直接查询和分析数据库内容，这在开发和调试阶段极为高效：
{"mcpServers":{"postgres":{"command":"uvx","args":["mcp-server-postgres"],"env":{"DATABASE_URL":"postgresql://user:pass@localhost:5432/mydb"}}}}典型用途：
| 用途 | 调用示例 |
|---|---|
| 查询表结构 | “显示 users 表的所有字段和类型” |
| 执行查询 | “查询最近 7 天的订单总额” |
| 数据分析 | “统计每个分类的商品数量” |
| 生成测试数据 | “根据 schema 生成 100 条测试数据” |
4.4 常用 Server 速查表
| Server | 语言 | 能力 | 配置复杂度 |
|---|---|---|---|
| filesystem | Node.js | 文件读写、搜索 | 低 |
| git | Python | Git 操作 | 低 |
| postgres | Python | PostgreSQL 查询 | 低 |
| sqlite | Python | SQLite 查询 | 低 |
| fetch | Python | URL 抓取 | 低 |
| brave-search | Node.js | 网络搜索 | 中（需 API Key） |
| memory | Node.js | 知识图谱存储 | 低 |
| sequential-thinking | Node.js | 结构化推理 | 低 |
五、自定义 Server 的接入流程
当你开发了自己的 MCP Server（前面章节已经学过如何用 Python 和 TypeScript 开发），接入 Cursor 只需几步。
5.1 接入步骤
第一步：确保 Server 可以独立运行 ↓ 第二步：确定启动命令和参数 ↓ 第三步：在 Cursor 中添加配置 ↓ 第四步：验证连接和工具发现 ↓ 第五步：在 Chat / Composer 中测试调用5.2 Python Server 接入示例
假设你开发了一个日志分析 Server，入口文件为log_analyzer.py：
{"mcpServers":{"log-analyzer":{"command":"python","args":["/home/me/tools/log_analyzer.py"],"env":{"LOG_DIR":"/var/log/my-app","MAX_LINES":"10000"}}}}如果使用了uv管理依赖，可以用uv run启动：
{"mcpServers":{"log-analyzer":{"command":"uv","args":["run","--directory","/home/me/tools/log-server","python","main.py"]}}}5.3 TypeScript Server 接入示例
假设你开发了一个 API 网关 Server，编译后的入口为dist/index.js：
{"mcpServers":{"api-gateway":{"command":"node","args":["/home/me/tools/api-gateway/dist/index.js"],"env":{"API_BASE_URL":"https://api.example.com","API_KEY":"sk-xxx"}}}}开发阶段可以用ts-node直接运行 TypeScript 源码：
{"mcpServers":{"api-gateway-dev":{"command":"npx","args":["ts-node","/home/me/tools/api-gateway/src/index.ts"]}}}5.4 验证连接
配置完成后，验证步骤：
| 步骤 | 操作 | 预期结果 |
|---|---|---|
| 1 | 保存配置文件 | — |
| 2 | 在设置界面查看 MCP 面板 | Server 状态为绿色/Running |
| 3 | 展开 Server 详情 | 能看到发现的 Tools 列表 |
| 4 | 在 Chat 中输入@server-name | 自动补全出现该 Server |
| 5 | 让 AI 调用一个简单工具 | 正确返回结果 |
5.5 常见接入问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| Server 一直显示 Starting | 启动命令错误或依赖缺失 | 在终端手动运行启动命令排查 |
| 绿灯但没有 Tools | Server 未正确注册工具 | 检查@mcp.tool()或setRequestHandler代码 |
| 工具调用返回空 | 环境变量未注入 | 检查env配置，在 Server 端打印 env 验证 |
| 偶尔断连 | Server 崩溃或超时 | 添加异常处理和日志，检查内存使用 |
六、Cursor MCP 使用最佳实践
6.1 按需配置，避免过载
不要一次性配置太多 Server。每个 Server 都是独立进程，过多 Server 会消耗系统资源，同时也会让 AI 在工具选择时产生混淆。建议根据当前工作内容动态启用：
| 工作场景 | 推荐启用的 Server |
|---|---|
| 日常编码 | filesystem, git |
| 数据库开发 | filesystem, git, postgres/sqlite |
| 文档编写 | filesystem, fetch |
| 线上排查 | filesystem, log-analyzer, server-monitor |
| API 对接 | filesystem, api-gateway, fetch |
6.2 工具描述要精准
Cursor 的 AI 根据 Tool 的description字段判断何时使用它。描述越清晰，路由越准确：
# 差的描述 —— AI 不知道何时使用@mcp.tool()defquery(data:str)->str:"""查询数据"""...# 好的描述 —— AI 能精准匹配意图@mcp.tool()defsearch_logs_by_keyword(keyword:str,hours:int=24)->str:""" 在应用日志中按关键词搜索最近 N 小时的日志记录。 当用户需要排查错误、查找特定事件或分析日志趋势时使用此工具。 参数: keyword: 搜索关键词，支持正则表达式 hours: 搜索时间范围（小时），默认最近 24 小时 """...6.3 安全边界
| 安全措施 | 说明 |
|---|---|
| 文件访问白名单 | filesystem Server 只配置需要的目录 |
| 数据库只读 | 生产数据库的 Server 只暴露查询工具 |
| 敏感信息保护 | API Key 等通过env注入，不硬编码 |
| 定期审查授权 | 检查 Agent 模式下的自动调用记录 |
本篇小结
| 知识点 | 要点 |
|---|---|
| 配置方式 | 图形界面或 JSON 文件（~/.cursor/mcp.json和.cursor/mcp.json） |
| 工作流融合 | Chat 用@引用、Composer 多文件编辑、Agent 自主编排 |
| 常用 Server | filesystem、git、postgres、fetch 等 |
| 自定义接入 | 确定启动命令 → 配置 JSON → 验证连接 → 测试调用 |
| 最佳实践 | 按需配置、精准描述、安全边界 |
下篇预告
第 39 篇：实战案例：数据库查询 MCP Server
从零用 Python 开发一个支持 PostgreSQL 的 MCP Server，包含 Resources、Tools、Prompts 三大原语的完整实现。
如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。
