排查 Cursor 中的 MCP 服务器

Cursor MCP settings panel showing a server that failed to connect

MCP 服务器通过外部工具扩展 Cursor，但它们是具有自身依赖项的独立进程，当它们行为异常时，症状可能令人困惑：一个显示红色的服务器、一个无法刷新的工具列表，或者一个看起来毫无作用的断开按钮。本指南为您提供一种系统化的方法来诊断 Cursor 中的 MCP 问题，从快速分诊清单到针对每种常见故障模式的具体修复方法，并向您展示如何在 IDE 之外验证任何服务器，以便您判断问题出在服务器本身，还是在 Cursor 与其的连接上。

快速分诊清单

当 MCP 服务器行为异常时，请从上到下逐行查看此表。大多数问题在前三行内即可解决。

症状	首先要检查的内容	典型修复方法
服务器显示红色或无法启动	在终端中手动运行服务器命令	修复命令路径、缺少的运行时或环境变量
工具缺失或过时	您是否编辑了 mcp.json 而没有重启？	重启 Cursor 或重新加载窗口
断开按钮没有反应	进程是否真的已终止？	手动终止进程，然后重新连接
服务器出错且从不重试	Cursor 在某些失败后不会自动重试	将服务器关闭再打开，或重启
请求挂起然后超时	服务器启动或工具运行时太慢	预热依赖项，提高超时时间
身份验证错误	token 已过期或缺少环境变量	刷新 token，修复环境

服务器无法启动

最常见的 MCP 故障也是最简单的：Cursor 用来启动服务器的命令实际上并不起作用。Cursor 会严格按照您 mcp.json 中的命令，使用您提供给它环境来启动进程，如果该命令失败，服务器就永远不会出现。

命令路径错误

请完全按照 Cursor 会运行它的方式来检查命令。如果 mcp.json 写的是 command": "npx"，但 Cursor 进程内的 PATH 不包含 npx，那么启动就会失败。在 Windows 上这尤其常见，因为 GUI 应用程序继承的 PATH 与您的终端不同。

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\projects"]
    }
  }
}

在 Windows 上，使用可执行文件的绝对路径是可靠的修复方法。在 macOS 和 Linux 上，如果裸命令找不到，which npx 会告诉您绝对路径。

缺少 npx 或 uvx

许多 MCP 服务器以 npm 或 Python 包的形式发布，并通过 npx 或 uvx 启动。如果没有安装运行时，服务器就无法启动：

# Verify the runtimes exist
node --version    # Node 18+ for npx-based servers
npx --version
python --version
uvx --version     # install with: pip install uv

如果缺少 uvx，请安装它并重启您的终端和 Cursor，以便更新后的 PATH 被采用。

环境变量错误

需要 API 密钥的服务器在环境错误时，通常会启动后立即退出，或者启动后每次工具调用都返回错误。请阅读服务器的文档以获取确切的变量名，并记住 Cursor 只传递您在 env 块中列出的内容：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    }
  }
}

编辑 mcp.json 后工具未重新加载

您编辑了 mcp.json、保存了它、打开工具列表，但新工具不在那里。MCP 配置在服务器进程启动时被读取，因此编辑并非在所有情况下都会热重载。

保存文件并确认它是有效的 JSON。一个尾随逗号会使整个文件无法解析，每个服务器都可能失败。
完全重启 Cursor，或者如果您的版本在命令面板中提供重新加载选项，则重新加载窗口。
打开 MCP 设置面板并确认服务器显示为已连接。
开始一个新的对话。现有对话可能缓存了旧的工具列表，因此新工具只会在全新会话中出现。

重启胜过刷新

如果在 MCP 面板中将服务器关闭再打开无法采用您的更改，请执行完整的窗口重新加载或重启 Cursor。mcp.json 在连接时被读取，而过时的进程会持续提供其原始的工具列表，无论该文件现在写的是什么。

连接和重试问题

断开按钮没有反应

断开操作会停止 Cursor 这一侧的连接客户端，但对于 stdio 服务器，如果不能干净地关闭，实际的子进程可能会存留下来。结果是服务器看起来仍处于半存活状态，并拒绝干净的重新连接。当按钮似乎被忽略时：

# Find and kill a stubborn stdio MCP server process
# macOS / Linux:
ps aux | grep mcp
kill <PID>

# Windows PowerShell:
Get-Process | Where-Object { $_.ProcessName -like "*npx*" -or $_.ProcessName -like "*uvx*" }
Stop-Process -Id <PID> -Force

进程消失后，从 MCP 面板重新连接。下一次连接会使用您当前的配置启动一个全新的进程。

服务器出错后不重试

如果服务器在启动时或初始化期间返回错误，Cursor 通常不会在后台持续重试。服务器会停留在失败状态，直到您进行干预。手动重启选项按强制程度递增排列如下：

在 MCP 设置面板中将服务器关闭再打开。
重新加载 Cursor 窗口，以便所有 MCP 服务器重新连接。
完全退出并重启 Cursor。
如果进程卡住了，请如上所示将其终止，然后重新连接。

慢速服务器上的超时

首次运行时下载依赖项的服务器，或调用缓慢外部 API 的工具，可能会超过默认超时并报告一个看起来像服务器损坏的失败。典型情况是一个基于 npx 的服务器在其首次调用时，npm 在任何东西能够启动之前先去获取该包：

# Pre-warm an npx-based server so the first real connection is fast
npx -y @modelcontextprotocol/server-github --help

对于宿主机层面的超时，许多 MCP 宿主（包括 Cursor）会遵循常规的超时环境变量。在启动 Cursor 之前设置它们，可以给慢速服务器更多余量：

# macOS / Linux (add to your shell profile)
export MCP_TIMEOUT=30000        # server startup timeout in ms
export MCP_TOOL_TIMEOUT=120000  # individual tool call timeout in ms

如果服务器仍然太慢，请以不同方式托管它：将其作为持久的本地进程运行，并通过 SSE 或 HTTP 连接，而不是为每个会话启动它。

传输类型：stdio 与 SSE/HTTP

Cursor 支持两种 MCP 传输风格，若干排查步骤在它们之间有所不同。

方面	stdio	SSE / HTTP
运行方式	Cursor 启动进程	服务器单独运行，Cursor 连接到一个 URL
配置键	`command`、`args`、`env`	`url`（以及在支持的地方使用 headers）
常见故障	命令路径错误、缺少运行时	URL 错误、认证标头、CORS 或网络问题
重启行为	切换会重新连接进程	重新连接会访问远程端点
调试	手动运行命令	用 curl 访问端点，检查服务器日志

{
  "mcpServers": {
    "local-stdio-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "remote-http-server": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

对于 SSE 和 HTTP 服务器，在触碰 Cursor 之前，请先验证端点是否可达：

# A plain GET should return something, even if it is an auth error
curl -i https://mcp.example.com/sse

401 或 403 意味着传输没问题，而您的身份验证才是问题所在。超时或连接被拒绝意味着服务器已宕机，或者 URL 错误。

环境变量和密钥

项目级与全局 mcp.json

Cursor 从两个位置读取 MCP 配置：

全局： ~/.cursor/mcp.json（在 Windows 上：%USERPROFILE%\.cursor\mcp.json）。适用于每个项目。将个人服务器放在这里：您的 GitHub token、您的数据库浏览器、您的抓取工具。
项目： 仓库内的 .cursor/mcp.json。仅适用于该项目，并在提交时与队友共享。将项目专用的服务器放在这里：用于此仓库数据库的 schema MCP、此代码库使用的设计工具集成。

当服务器在两个位置都有定义时，预期项目配置会主导该项目。如果工具重复或消失，请检查两个文件中是否有同名的条目。

安全地传递密钥

Cursor 会从您的环境中展开 env 块中的 ${VAR_NAME} 占位符，因此密钥可以存放在 mcp.json 之外：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${MY_DATABASE_URL}"
      }
    }
  }
}

# Set the real value in your shell profile, not in the JSON file
export MY_DATABASE_URL="postgresql://user:password@localhost:5432/appdb"

不要将密钥提交到仓库

项目级的 .cursor/mcp.json 是您仓库中的一个普通文件。如果它包含一个明文的 API 密钥，那么每个克隆该仓库的人和每个 agent 都会获得该密钥。对任何敏感内容使用 ${VAR} 展开，并且如果项目 mcp.json 必须包含本地值，请将其添加到 .gitignore。

读取 MCP 日志

当症状不明确时，日志通常会指出真正的问题。Cursor 通过其输出基础设施来呈现 MCP 活动：

打开命令面板并运行显示输出面板的命令，或使用“视图”菜单。
在输出面板的通道下拉菜单中，选择 MCP 或 Cursor MCP 日志通道。
触发失败的操作，然后读取最新的条目。查找启动错误、非零退出代码，以及来自服务器 stderr 的堆栈跟踪。

典型的日志行及其含义：

[MCP] spawn npx ENOENT                 -> the runtime was not found on PATH
[MCP] server exited with code 1        -> the server crashed; run it manually for the real error
[MCP] initialize timed out             -> slow startup; pre-warm or raise the timeout
[MCP] tool call rejected: invalid args -> the model sent a bad schema; check the tool input

服务器端的 stderr 会被转发到这些日志中，因此来自服务器本身的 Python 回溯或缺少依赖项的异常通常会逐字出现在这里。

独立验证服务器

证明一个问题究竟是 Cursor 的还是服务器的，最快的方法是在没有 Cursor 的情况下运行该服务器。

手动运行命令

从 mcp.json 复制 command 和 args，并在一个普通终端中运行它们：

# Whatever your mcp.json launches, launch it yourself
npx -y @modelcontextprotocol/server-filesystem /tmp

一个健康的 stdio MCP 服务器会启动，并在 stdin 上静默等待 JSON-RPC 输入。如果您反而看到命令未找到的错误、崩溃或包安装失败，那么您已经找到了问题，而 Cursor 是无辜的。输入几个字符并按 Enter；一个纯粹的协议错误响应实际上是个好迹象，因为它证明该进程正在使用 JSON-RPC 通信。

使用 MCP 检查器

官方的 MCP 检查器会连接到一个服务器、列出其工具，并让您以交互方式调用它们：

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

这会打开一个本地 Web 界面，您可以在其中初始化服务器、列出工具，并用手写的参数调用其中一个。如果一个工具在检查器中可以工作但在 Cursor 中不行，那么差异通常在于环境：存在于您终端中但缺失于 Cursor 进程中的变量，或者不同的工作目录。如果该工具在检查器中同样失败，请先修复服务器；您在 Cursor 中做的任何更改都无济于事。

最小可用 mcp.json

当您的配置已经漂移成无法启动的状态时，可将此作为参考。它展示了一个 stdio 服务器和一个远程服务器，并带有环境变量展开：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "remote-search": {
      "url": "https://mcp.example.com/sse",
      "env": {
        "API_TOKEN": "${MY_MCP_TOKEN}"
      }
    }
  }
}

将其适配到您的服务器的清单：

将包名和参数替换为服务器文档中的那些。
在 Windows 上，如果找不到裸命令，请使用绝对可执行文件路径。
将密钥保留为 ${VAR} 占位符，并在您的 shell 配置文件中设置真实值。
验证 JSON，然后重启 Cursor，并在打开对话之前确认服务器显示为已连接。

一个错误的条目就能破坏整个文件

mcp.json 是作为单个 JSON 文档来解析的。一个尾随逗号或未加引号的值就会使整个文件无效，其中的每个服务器都可能一起启动失败，包括那些原本运行正常的。如果多个服务器同时挂掉，请先怀疑文件语法，再逐一怀疑每个服务器。

快速参考

目标	执行此操作
启动后服务器显示红色	手动运行命令；修复路径、运行时或环境
新工具未出现	重新加载窗口，然后开始一个全新的对话
断开无响应	终止子进程，然后重新连接
反复失败，无重试	将服务器关闭再打开，或重启 Cursor
首次运行超时	预热包，提高超时环境变量
怀疑是服务器而非 Cursor	通过手动运行或 MCP 检查器进行验证
怀疑是 Cursor 而非服务器	将您的环境与终端对比，并读取 MCP 日志通道

快速分诊清单​

服务器无法启动​

命令路径错误​

缺少 npx 或 uvx​

环境变量错误​

编辑 mcp.json 后工具未重新加载​

连接和重试问题​

断开按钮没有反应​

服务器出错后不重试​

慢速服务器上的超时​

传输类型：stdio 与 SSE/HTTP​

环境变量和密钥​

项目级与全局 mcp.json​

安全地传递密钥​

读取 MCP 日志​

独立验证服务器​

手动运行命令​

使用 MCP 检查器​

最小可用 mcp.json​

快速参考​