cursor-mcp

@qmediat.io/cursor-mcp

面向 Cursor CLI（cursor-agent）的 MCP 服务：通过模型上下文协议，使用套餐提供的任意模型 ID 运行 Cursor 的 Agent，包括 Composer、Claude、GPT、Gemini 和 Grok 系列。

为什么使用此服务？

• 任意 Cursor 模型 — model ID 会按原样传递给 cursor-agent --model；cursor_models 会列出 CLI 提供的模型（套餐中的 Composer、Claude、GPT、Gemini 和 Grok 系列）
• 5 种工具 — Agent 执行、会话续接、模型列表、会话列表、健康检查
• 并行执行 — 通过内置并发控制（信号量）同时运行多个模型
• 受保护的执行 — 使用不带 shell 的 spawn，仅通过操作者的环境启用自动批准（绝不将其作为工具参数）；客户端取消操作或超时会终止子进程及其进程组（发送 SIGTERM，5 秒后发送 SIGKILL；在 Windows 上仅终止 cursor-agent 本身）
• 最少依赖 — 仅依赖 @modelcontextprotocol/sdk 和 zod
• 会话管理 — 在多次调用之间续接对话

快速开始

先决条件

1. Node.js >= 22.0.0（开发本项目时，npm run lint 使用的 Babel 8 需要 22.18 或 24.11）
2. 已安装并完成身份验证的 Cursor CLI：

# Install the Cursor CLI (installs `agent`; `cursor-agent` stays as a legacy alias — the one this server resolves)
curl https://cursor.com/install -fsS | bash

# Authenticate (a Cursor account whose plan includes agent usage — see cursor.com/docs/models-and-pricing)
agent login

需要 Node.js 22 或更高版本。

安装

claude mcp add --scope user cursor-cli -- npx -y @qmediat.io/cursor-mcp

或者手动安装（见下文）。npm install -g @qmediat.io/cursor-mcp 会安装 cursor-mcp 命令，可在任意配置中替代 npx 命令行。

配置

Claude Code（~/.claude.json）

{
  "mcpServers": {
    "cursor-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@qmediat.io/cursor-mcp"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "cursor-cli": {
      "command": "npx",
      "args": ["-y", "@qmediat.io/cursor-mcp"]
    }
  }
}

本地开发

{
  "mcpServers": {
    "cursor-cli": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/cursor-mcp/dist/index.js"]
    }
  }
}

环境变量

可用工具

这两个 Agent 工具都会使用 --output-format stream-json 运行 cursor-agent：答案、它的 session_id、request_id、cursor-agent 报告的模型、运行时长、工具调用次数以及已更改的文件（写入/编辑目标，每个目标仅列一次）都会以文本和 structuredContent（已发布 outputSchema）的形式返回。请求中带有进度令牌的客户端会针对每个事件（模型、工具调用、助手消息）收到一条 notifications/progress，因此运行十分钟也不会让人觉得程序卡住了。

模型

model 会按原样传递给 cursor-agent --model，因此已安装 CLI 接受的任何 ID 都可使用——当前列表和价格见 cursor.com/docs/models-and-pricing，cursor_models 会返回 CLI 报告的内容（cursor-agent models）。auto（默认值）会让 Cursor 自行选择。本 README 有意不列出任何 ID：Cursor 增删模型的速度远快于此软件包的发布速度，而正是 README 中的列表导致 1.0.x 拒绝所有当前模型。

模式

并行执行

通过并行调用工具，同时运行多个模型：

# In Claude Code, spawn 3 Agent subprocesses:
Agent 1: cursor_agent with model=<a Composer id from cursor_models> → "Review this code"
Agent 2: cursor_agent with model=<a Claude id from cursor_models> → "Review this code"
Agent 3: cursor_agent with model=<a GPT id from cursor_models> → "Review this code"

内置信号量（默认值：3）会将超出的请求排队，以避免触发速率限制错误。

安全

• 不执行 Shell 命令——使用带参数数组的 child_process.spawn；提示词位于 -- 分隔符之后，且会话 ID 必须是单个词，因此两者都不会被解读为 cursor-agent 选项（提示词或会话 ID 为 -f 时，也不会变成 --force）
• 不存储凭据——cursor-agent 自行处理 OAuth
• 不发送 HTTP 请求——纯 CLI 封装，除 cursor-agent 外不访问网络
• 进程清理——客户端取消（MCP 请求信号）或超时会终止子进程及其进程组中的辅助进程（POSIX；Windows 上没有进程组，只会向 cursor-agent 本身发送信号）：先发送 SIGTERM，再于 CURSOR_KILL_GRACE_MS（5 秒）后发送 SIGKILL；只有子进程本身退出后，调用和并发名额才会释放；服务自身关闭时，也会以相同方式结束所有正在运行的进程组，因此不会有 Agent 在服务退出后继续运行
• 自动批准受限——--force 需要显式设置环境变量 CURSOR_ALLOW_YOLO=true，LLM 无法控制该变量；未设置时，Agent 只会提出更改建议；CURSOR_SANDBOX=enabled 会限制自动批准的 Agent；这同样适用于 cursor_agent 和 cursor_reply
• 可信工作区——每次调用都会针对指定的 workspace 运行 cursor-agent --trust（默认为服务的当前工作目录），因此 Agent 不会询问是否信任该目录：workspace 只应指向你希望它操作的目录
• 限制并发——信号量可防止资源耗尽

完整详情请参阅 SECURITY.md。

监督式编码技能

可选的 Claude Code 技能，可让 Claude Code 充当监督者，由任意 Cursor 模型负责编码。

**工作原理：**Claude Code 分析任务，通过 cursor_agent 向 Cursor 发送精确指令，从磁盘读取实际文件来检查输出，并通过 cursor_reply 反复迭代，直到满意为止（最多 3 轮）。

**前提条件：**必须先在 Claude Code 中安装并配置 cursor-cli MCP 服务（即此软件包）。

用法

/cursor-code <task>                              # default: auto (Cursor chooses)
/cursor-code --model <id> <task>                 # any id cursor_models lists

运行 cursor_models，列出 CLI 提供的模型 ID。

安装技能

mkdir -p ~/.claude/skills/cursor-code

使用以下内容创建 ~/.claude/skills/cursor-code/SKILL.md：

---
name: cursor-code
description: Delegate coding to any Cursor model while Claude Code supervises.
  Use when user says "cursor-code", "delegate to cursor", "cursor code this",
  or "/cursor-code". Works with any model id cursor_models lists (the Composer,
  Claude, GPT, Gemini and Grok families on your Cursor plan).
metadata:
  version: 1.1.0
---

# Supervised Coding: Claude Code (Supervisor) -> Cursor (Coder)

You are the **supervisor** (Claude Code). A Cursor model is the **coder**.
You give precise instructions, the coder writes code, you review and iterate.

## Parsing

Extract from user input:
- `--model <id>` -> model to use (default: `auto`, Cursor chooses)
- Everything else -> the task description

If user says a model name naturally (e.g. "use composer", "with gemini", "z grok"),
extract it and map to an id from cursor_models.

## Workflow

### Step 1: Analyze
- Read the relevant files to understand current state
- Break the user's task into a single, focused coding instruction
- Identify: target files, constraints, acceptance criteria

### Step 2: Instruct
Call `cursor_agent` with:
- `model`: extracted model or `auto`
- `workspace`: current working directory
- `prompt`: precise instruction with file paths, function names, constraints
- Keep prompt focused -- one task per call, not an entire feature
- Extract and store the `session_id` from the response for use in Step 4

Output before calling: `[cursor-cli -> <model>]`

### Step 3: Verify
After the coder returns:
- Run `git diff --name-only` to discover ALL files the coder modified
- Read EVERY modified file from disk (use Read tool) -- not just the ones from your prompt
- Diff against expectations
- Check: correctness, edge cases, security, type safety

### Step 4: Iterate (max 3 rounds)
If issues found:
- Call `cursor_reply` with the same session_id
- Give specific fix instructions (file:line, what's wrong, what to do)
- Re-verify after each round
- If the coder is fundamentally off-track (wrong approach, not just small bugs),
  abandon the session early and start fresh with a more explicit prompt

### Step 5: Report
Summarize to the user:
- Model used (confirm from response, not just request)
- What was done
- Files changed
- Rounds needed (1 = clean, 2-3 = corrections applied)
- Any manual fixes Claude Code applied directly

## Rules
- ONE task per cursor_agent call -- don't batch entire features
- ALWAYS read files from disk after coder finishes
- NEVER trust cached file contents -- Cursor writes directly to disk
- Set timeout_seconds appropriately (30-120s for typical tasks)
- If the task is trivial (< 5 lines) -- just do it yourself, don't delegate
- Follow model transparency rules -- always state [cursor-cli -> model] before call
- If cursor_agent/cursor_reply fails (timeout, auth, CLI not found) -- report the error to the user and run cursor_health to diagnose. Do not retry silently
- If unsure about valid model IDs -- call cursor_models first

创建技能文件后，重启 Claude Code。

开发

git clone https://github.com/qmediat/cursor-mcp.git
cd cursor-mcp
npm install
npm run build
npm run lint   # structure rules, repeated blocks, the baseline ratchet (docs/SYSTEMIC.md §1)
npm run format # Prettier (npm run lint checks it)
node dist/index.js

请参阅 CONTRIBUTING.md 了解相关指南；npm test 会构建并运行 smoke 和 argv 测试。

商标与关联关系

Cursor 是 Anysphere 的商标。这是由 Quantum Media Technologies sp. z o.o. 发布并由社区维护的独立集成项目；它与 Anysphere 无关联，也未获得其赞助或认可。通过此服务使用 Cursor API 或 CLI，须遵守 Anysphere 自身的条款，并使用你自己的 API 密钥或账户。

许可证

MIT - Quantum Media Technologies sp. z o.o.

由 Quantum Media Technologies 制作 · 更多来自 qmediat 的开源项目