在 Cursor 中配置 MCP 服务器：从零到生产部署的完整指南

主题: cursor-mcp-server-setup-guide更新于: 2026/6/24作者：AgentFactory 技术团队

如果你正在使用 Cursor 的 AI Agent 功能，却受限于它无法直接操作数据库、GitHub Issue 或 Figma 设计文件，那么 MCP（Model Context Protocol）服务器就是你需要的东西。本文将手把手教你如何在 Cursor 中配置 MCP 服务器，并解决生产环境中常见的坑。

它解决什么问题 / 适用场景

MCP 服务器本质上是一个标准化适配层，让 Cursor 的 AI Agent 能够通过统一协议调用外部工具。你不再需要为每个工具手写 API 集成代码，Agent 会自动发现可用的工具并动态调用。

最适合以下场景：

从编辑器内直接查询 PostgreSQL 数据库或执行 SQL 查询
让 Agent 自动创建、更新或关闭 GitHub Issue
获取 Figma 设计令牌并直接生成匹配的 CSS 变量
跨团队共享 MCP 服务器配置，实现集中式凭证管理和审计

与 LLM 的兼容性： MCP 并非 Cursor 专属。Claude Desktop 原生支持，OpenAI GPT（2025 年 5 月后）、Google Gemini（2025 年 4 月后）也已跟进。这意味着你可以在不同 AI 客户端间复用同一套 MCP 服务器配置。

安装与快速上手

1. 理解两种传输方式

MCP 服务器支持两种通信模式，选择哪种取决于你的使用场景：

传输方式	适用场景	配置字段
stdio	本地开发、单机使用	`command` + `args` + `env`
Streamable HTTP	远程团队共享、生产部署	`url` + `headers`

2. 配置 Cursor 的 MCP 设置

在 Cursor 中，MCP 配置存放在 ~/.cursor/mcp.json（全局）或项目根目录的 .cursor/mcp.json（项目级）。推荐使用全局配置，避免将 API 密钥提交到版本控制。

基本配置模板：

JSON
{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "remote-api": {
      "url": "https://mcp-gateway.yourcompany.com/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

关键点： command 和 url 是必填字段，但两者互斥——stdio 传输用 command，HTTP 传输用 url。不要同时填写。

3. 验证配置是否生效

配置完成后，在 Cursor 中重启 AI 功能（Cmd+Shift+P → "Reload Window"），然后打开 MCP 面板（通常位于右下角或通过命令面板搜索 "MCP"）。你应该能看到已连接的服务器列表及其暴露的工具。

如果显示 "No Tools Found"，请跳到后面的报错排查部分。

核心配置 / 参数说明

参数	必填	传输方式	说明	典型值
`command`	是	stdio	启动 MCP 服务器的可执行文件	`npx`, `docker`, `python`, `node`
`args`	否	stdio	传递给 command 的参数数组	`["-y", "@modelcontextprotocol/server-github"]`
`env`	否	stdio	运行时环境变量，推荐存放 API 密钥	`{"GITHUB_TOKEN": "ghp_xxx"}`
`url`	是	HTTP	远程 MCP 服务器的 HTTP 端点	`https://mcp.example.com/mcp`
`headers`	否	HTTP	HTTP 请求头，通常用于认证	`{"Authorization": "Bearer xxx"}`

关于 env 字段的注意事项： 直接硬编码密钥在 mcp.json 中是不安全的。更好的做法是使用环境变量引用，例如 "GITHUB_TOKEN": "${GITHUB_TOKEN}"，然后在启动 Cursor 前设置好环境变量。或者，将 mcp.json 添加到 .gitignore。

与同类方案对比

对比维度	MCP 服务器	直接使用 API	GitHub CLI
集成方式	标准化协议，Agent 自动发现工具	需手写每个工具的调用逻辑	手动执行命令
跨 IDE 兼容	支持 Cursor、Claude Desktop 等	需为每个平台重写	仅命令行
动态工具发现	是，服务器暴露工具列表	否，需硬编码	否
学习成本	低，配置即用	高，需了解每个 API	中，需记忆命令
生产审计	需额外网关支持	可自行实现	无内置审计

亮点总结： MCP 的核心优势在于标准化和动态发现。你不需要为每个工具写适配代码，Agent 会自动加载可用的工具列表。这对于需要频繁切换工具集的团队尤其有价值。

生产环境实践与注意事项

1. 40 工具限制

Cursor 对单个 MCP 服务器暴露的工具总数有约 40 个的上限。超出后，Agent 可能静默丢失部分工具访问，且不会报错。

应对策略：

按功能领域拆分服务器（如 github-server、database-server、figma-server）
每个服务器暴露 5-10 个精心设计的工具，而不是一个包含 30 个工具的巨型服务器
在 Cursor 设置中禁用不常用的工具

2. 并发冲突与文件锁定

如果多个 Cursor 实例同时访问同一个文件型 MCP 服务器（如 sqlite-mcp），可能会遇到文件锁定错误：

SQLite file locked

解决方案：

启用 SQLite 的 WAL 模式（Write-Ahead Logging）：PRAGMA journal_mode=WAL;
确保只有一个 Cursor 实例访问该数据库
考虑使用 PostgreSQL 等支持并发的数据库替代
在 MCP 服务器配置中增加连接超时和重试逻辑

3. 凭证管理

env 字段中的 API 密钥若硬编码在 mcp.json 中，极易被提交到版本控制系统。

安全建议：

使用环境变量引用："GITHUB_TOKEN": "${GITHUB_TOKEN}"
将 .cursor/mcp.json 添加到 .gitignore
使用全局配置 ~/.cursor/mcp.json 避免项目级泄露
对于远程服务器，使用 headers 字段中的 Bearer 令牌，并确保令牌通过安全渠道分发

4. 网络安全

远程 MCP 服务器（Streamable HTTP）暴露在网络上，需配置：

HTTPS 加密传输
API 密钥或 OAuth 认证
IP 白名单限制访问来源
定期轮换密钥

5. 无内置审计

默认 MCP 服务器不提供操作日志。如果需要审计功能，需通过 MCP 网关（如 TrueFoundry MCP Gateway）实现集中式日志记录和权限管理。

常见报错与排查

报错 1：No Tools Found

现象： Cursor 显示 MCP 服务器已连接，但工具列表为空。

排查步骤：

在终端中手动运行 mcp.json 中的命令，检查输出错误
确认 Node.js/Python 已安装且在 PATH 中
检查包版本是否存在（例如 npx -y @modelcontextprotocol/server-github）
确保所有必需的环境变量已设置且非空
查看 Cursor 的开发者控制台（Help → Toggle Developer Tools）获取详细日志

报错 2：Connection timeout

现象： 远程 MCP 服务器在指定时间内未响应。

排查步骤：

检查服务器 URL 是否正确
确认网络连接和防火墙规则允许出站请求
使用 curl -v https://mcp.example.com/mcp 测试服务器可达性
考虑使用 stdio 传输作为本地替代

报错 3：Paths not absolute

现象： 在 mcp.json 中指定的文件路径（如数据库路径）不是绝对路径，导致服务器无法找到资源。