Cursor Agent MCP

🚀 Cursor Agent MCP Server

Cursor Agent MCP Server 是一个轻量级、安全加固的模型上下文协议（MCP）服务器，它封装了 cursor-agent 命令行工具（CLI），并提供了多个适用于 Claude 的工具，可用于聊天、仓库分析、代码搜索、规划等功能。

🚀 快速开始

安装

1. 克隆或下载本仓库。
2. 为 MCP 服务器安装依赖：

cd ./cursor-agent-mcp
npm ci        # 或者: npm install

3. 确保 cursor-agent CLI 已安装并在系统路径中（或者设置 CURSOR_AGENT_PATH）：

cursor-agent --version

4. 运行 MCP 服务器：

# 从服务器目录运行
node ./server.js

# 或者从仓库根目录使用提供的脚本运行
npm --prefix ./cursor-agent-mcp run start

快速测试（无需 MCP 主机）

提供了一个小型客户端，可用于列出工具并通过标准输入输出调用其中一个工具：

# 列出工具并使用提示调用聊天工具
node ./cursor-agent-mcp/test_client.mjs "Hello from smoke test"

# 使用 --help 运行原始工具（无隐式 --print）
TEST_TOOL=cursor_agent_raw TEST_ARGV='["--help"]' node ./cursor-agent-mcp/test_client.mjs

✨ 主要特性

• 以“动词为中心”的命令行工具为模型的多工具界面。
• 在 Claude Code 和其他 MCP 主机中表现良好。
• 安全的进程生成（无 shell），强大的超时处理。
• 可选的提示回显，便于在主机内部进行调试。
• 可通过环境变量配置默认值（模型、强制选项、超时时间、可执行文件路径）。
• 向后兼容的单轮聊天旧版工具。

📦 安装指南

安装步骤

1. 克隆或下载仓库：

# 克隆仓库
git clone <仓库地址>

2. 安装依赖：

cd ./cursor-agent-mcp
npm ci        # 或者: npm install

3. 检查 cursor-agent CLI：

cursor-agent --version

若未找到，可设置 CURSOR_AGENT_PATH 为其绝对路径。 4. 运行服务器：

# 从服务器目录运行
node ./server.js

# 或者从仓库根目录使用提供的脚本运行
npm --prefix ./cursor-agent-mcp run start

是否需要 npx？

不需要。此服务器直接从仓库运行，未发布到 npm（package.json 中设置 "private": true）。按照上述步骤安装依赖后，使用 Node 执行 server.js。

若之后将其发布为 npm 包并在 package.json 中添加 bin 条目，则可以使用 npx 运行，并将 MCP 主机指向该可执行文件。在此之前，建议使用此处显示的基于 Node 的命令。

💻 使用示例

基础用法

在 Claude 中使用这些工具，参数与“工具”部分的 JSON 字段一一对应。例如，调用聊天工具：

{
  "name": "cursor_agent_chat",
  "arguments": { "prompt": "Explain SIMD in one paragraph", "output_format": "markdown" }
}

高级用法

对于高级使用场景，建议使用 cursor_agent_raw 以精确控制参数和输出行为。例如：

{ "name": "cursor_agent_raw", "arguments": { "argv": ["-m","gpt-5","What is SIMD?"], "print": true } }

📚 详细文档

工具列表

• cursor_agent_chat：单轮聊天工具，将提示作为最终位置参数传递。

{
  "name": "cursor_agent_chat",
  "arguments": { "prompt": "Explain SIMD in one paragraph", "output_format": "markdown" }
}

• cursor_agent_edit_file：基于提示的文件编辑包装器，要求代理编辑文件或提出补丁。

{
  "name": "cursor_agent_edit_file",
  "arguments": {
    "file": "src/app.ts",
    "instruction": "Extract the HTTP client into a separate module and add retries",
    "dry_run": true,
    "output_format": "markdown"
  }
}

• cursor_agent_analyze_files：基于提示的仓库/文件分析工具，列出要关注的路径。

{
  "name": "cursor_agent_analyze_files",
  "arguments": {
    "paths": ["src", "scripts"],
    "prompt": "Give me a concise architecture overview with module boundaries"
  }
}

• cursor_agent_search_repo：基于提示的代码搜索工具，可选择包含/排除文件。

{
  "name": "cursor_agent_search_repo",
  "arguments": {
    "query": "fetch(",
    "include": ["src/**/*.ts", "app/**/*.tsx"],
    "exclude": ["node_modules/**", "dist/**"],
    "output_format": "markdown",
    "echo_prompt": true
  }
}

• cursor_agent_plan_task：基于提示的规划工具，返回目标的编号计划。

{
  "name": "cursor_agent_plan_task",
  "arguments": {
    "goal": "Set up CI to lint and test this repo",
    "constraints": ["GitHub Actions", "Node 18"]
  }
}

• cursor_agent_raw：将原始参数转发到 CLI。

{ "name": "cursor_agent_raw", "arguments": { "argv": ["--help"], "print": false } }

{ "name": "cursor_agent_raw", "arguments": { "argv": ["-m","gpt-5","What is SIMD?"], "print": true } }

• cursor_agent_run (legacy)：原始单轮聊天包装器，为兼容性保留。

{
  "name": "cursor_agent_run",
  "arguments": { "prompt": "Your prompt here", "output_format": "markdown" }
}

MCP 主机配置示例

Claude Code/Claude Desktop 配置示例：

{
  "mcpServers": {
    "cursor-agent": {
      "command": "node",
      "args": ["/abs/path/to/cursor-agent-mcp/server.js"],
      "env": {
        "CURSOR_AGENT_ECHO_PROMPT": "1",
        "CURSOR_AGENT_FORCE": "true",
        "CURSOR_AGENT_PATH": "/home/you/.local/bin/cursor-agent",
        "CURSOR_AGENT_MODEL": "gpt-5",
        "CURSOR_AGENT_IDLE_EXIT_MS": "0",
        "CURSOR_AGENT_TIMEOUT_MS": "60000"
      }
    }
  }
}

可选：启用调试日志

添加 DEBUG_CURSOR_MCP=1 以将诊断信息打印到标准错误输出（生成参数、提示预览、退出信息）。在集成或故障排除时很有用。

{
  "mcpServers": {
    "cursor-agent": {
      "command": "node",
      "args": ["/abs/path/to/cursor-agent-mcp/server.js"],
      "env": {
        "CURSOR_AGENT_ECHO_PROMPT": "1",
        "CURSOR_AGENT_FORCE": "true",
        "CURSOR_AGENT_PATH": "/home/you/.local/bin/cursor-agent",
        "CURSOR_AGENT_MODEL": "gpt-5",
        "CURSOR_AGENT_IDLE_EXIT_MS": "0",
        "CURSOR_AGENT_TIMEOUT_MS": "60000",
        "DEBUG_CURSOR_MCP": "1"
      }
    }
  }
}

🔧 技术细节

工作原理

所有工具调用最终都会调用同一个执行器 JavaScript.invokeCursorAgent()，它会：

• 解析 cursor-agent 可执行文件（显式路径或系统路径）。
• 默认注入 --print 和 --output-format <fmt>。
• 根据环境变量/参数可选地添加 -m <model> 和 -f。
• 流式传输标准输出/标准错误输出，并强制执行总超时。
• 可选地终止长时间闲置的进程（默认禁用）。

旧版包装器 JavaScript.runCursorAgent() 接受一个 prompt 和可选标志，组成参数并委托给执行器。

环境变量

服务器可识别的环境变量：

📄 许可证

本项目采用 MIT 许可证，详情见 cursor-agent-mcp/package.json。

其他信息

成本控制提示

• 首选精确范围：
  • 在 cursor_agent_search_repo 中使用 include/exclude 通配符，在 cursor_agent_analyze_files 中使用精心策划的 paths。
• 有意选择输出格式：
  • 使用 "text" 或 "markdown" 以获得简洁答案。仅在真正需要结构化输出时使用 "json"（通常较大）。
• 选择适合任务的模型：
  • 将 CURSOR_AGENT_MODEL 设置为经济高效的默认值；仅在必要时为每个工具调用覆盖。
• 避免不必要的回显/调试：
  • CURSOR_AGENT_ECHO_PROMPT=1 在设置期间很有用，但之后禁用以节省主机日志中的令牌。
  • 正常使用时保持 DEBUG_CURSOR_MCP 关闭；它会将诊断信息写入标准错误输出（不计入主机会话令牌，但会产生噪音）。
• 控制运行时间而非闲置终止：
  • 保持 CURSOR_AGENT_IDLE_EXIT_MS="0"，以免有效运行在生成过程中被中断。使用 CURSOR_AGENT_TIMEOUT_MS 和聚焦的提示来限制成本/时间。
• 谨慎使用 cursor_agent_raw：
  • 它功能强大，可流式传输详细会话；为了最经济的使用方式，首选具有简洁提示和 "text" 输出的聚焦工具。

故障排除

• “cursor-agent not found”：
  • 将 CURSOR_AGENT_PATH 设置为 CLI 的绝对路径，或确保它在系统路径中。
• “No prompt provided for print mode”：
  • 以 print=true 调用 RAW 工具但未提供提示。要么在参数中提供提示，要么将 print 设置为 false。
• 生成过程中过早终止：
  • 增加 CURSOR_AGENT_TIMEOUT_MS，并将 CURSOR_AGENT_IDLE_EXIT_MS 保持为 "0"。
• 工具输出为空：
  • 验证提供商凭证和模型名称。使用 cursor_agent_raw 并传入 argv: ["--version"] 以确认 CLI 正常运行。

开发

• 直接启动服务器：

node ./cursor-agent-mcp/server.js

• 测试客户端：

node ./cursor-agent-mcp/test_client.mjs "hello"
TEST_TOOL=cursor_agent_raw TEST_ARGV='["--help"]' node ./cursor-agent-mcp/test_client.mjs

• 开发时有用的环境变量：

DEBUG_CURSOR_MCP=1 CURSOR_AGENT_ECHO_PROMPT=1

关键入口点

• 执行器：JavaScript.invokeCursorAgent()
• 旧版运行器：JavaScript.runCursorAgent()
• 工具注册起始位置：JavaScript.server.tool()

安全注意事项

• 子进程以 shell: false 生成，以避免 shell 注入和引号问题。
• 输入使用 Zod 进行验证，未知类型将被拒绝。
• 避免记录机密信息；调试仅打印参数和最小环境上下文。

版本信息

当前服务器版本：1.1.0（见 cursor-agent-mcp/package.json）

致谢

• MCP 协议和 SDK 由 Model Context Protocol 团队提供。
• 灵感来源：多动词 MCP 服务器，如 gemini-mcp-tool。