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。