内容
# @qmediat.io/cursor-mcp
[](https://www.npmjs.com/package/@qmediat.io/cursor-mcp)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
用于 [Cursor CLI](https://cursor.com/docs/cli) 的 MCP 服务器 — 通过 [Model Context Protocol](https://modelcontextprotocol.io) 访问 Composer 2、Claude、GPT、Gemini 和 Grok 模型。
## 为什么使用这个服务器？
- **多模型访问** — 通过单一接口访问 Composer 2、Claude 4.6 Opus、GPT-5.4、Gemini 3 Pro、Grok、Kimi K2.5
- **5 种工具** — 代理执行、会话继续、模型列表、会话列表、健康检查
- **并行执行** — 使用内置并发控制（信号量）同时运行多个模型
- **安全优先** — `spawn`（无 shell），环境变量控制（从不 LLM 可控），AbortSignal 取消
- **最小依赖** — 仅 `@modelcontextprotocol/sdk` + `zod`
- **会话管理** — 跨调用恢复对话
## 快速开始
### 先决条件
1. **Node.js >= 22.0.0**
2. **Cursor CLI** 已安装并认证：
```bash
# 安装 cursor-agent
curl https://cursor.com/install -fsS | bash
# 认证（需要 Cursor Pro/Business 订阅）
cursor-agent login
```
### 安装
```bash
npm install -g @qmediat.io/cursor-mcp
```
或直接使用 npx 运行：
```bash
npx @qmediat.io/cursor-mcp
```
## 配置
### Claude Code (`~/.claude.json`)
```json
{
"mcpServers": {
"cursor-cli": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@qmediat.io/cursor-mcp"]
}
}
}
```
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"cursor-cli": {
"command": "npx",
"args": ["-y", "@qmediat.io/cursor-mcp"]
}
}
}
```
### 本地开发
```json
{
"mcpServers": {
"cursor-cli": {
"type": "stdio",
"command": "node",
"args": ["/path/to/cursor-mcp/dist/index.js"]
}
}
}
```
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `CURSOR_MAX_CONCURRENCY` | 否 | `3` | 最大并发 cursor-agent 进程 |
| `CURSOR_ALLOW_YOLO` | 否 | `false` | 启用 `--force` 模式（自动批准所有工具调用）。**危险** — 仅适用于受信任的环境 |
## 可用工具
| 工具 | 描述 | 关键参数 |
| --- | --- | --- |
| `cursor_agent` | 使用 Cursor 的 AI 代理执行提示 | `prompt`、`model`、`mode`、`workspace`、`cloud`、`timeout_seconds` |
| `cursor_reply` | 继续现有的代理会话 | `prompt`、`session_id`、`model`、`timeout_seconds` |
| `cursor_models` | 列出所有可用的 AI 模型 | — |
| `cursor_sessions` | 列出代理会话（此服务器实例） | — |
| `cursor_health` | 检查安装、身份验证和配置 | — |
### 模型
| 模型 | 描述 | 价格（每 100 万个 token 输入/输出） |
| --- | --- | --- |
| `auto` | Cursor 自动选择（默认） | 变动 |
| `composer-2` | Cursor Composer 2 — 200K 上下文 | $0.50 / $2.50 |
| `composer-2-fast` | Composer 2 快速变体 | $1.50 / $7.50 |
| `cursor/claude-4-sonnet` | 通过 Cursor 的 Claude 4 Sonnet | 变动 |
| `cursor/claude-4.5-sonnet` | 通过 Cursor 的 Claude 4.5 Sonnet | 变动 |
| `cursor/claude-4.6-opus-high` | 通过 Cursor 的 Claude 4.6 Opus | 变动 |
| `cursor/gpt-5.1` | 通过 Cursor 的 GPT-5.1 | 变动 |
| `gpt-5.4` | GPT-5.4 | 变动 |
| `cursor/gemini-3-flash` | 通过 Cursor 的 Gemini 3 Flash | 变动 |
| `gemini-3-pro` | Gemini 3 Pro | 变动 |
| `cursor/grok` | 通过 Cursor 的 Grok | 变动 |
| `kimi-k2.5` | Moonshot Kimi K2.5 | 变动 |
### 模式
| 模式 | 描述 |
| --- | --- |
| `agent` | 完整功能 — 文件编辑、终端、搜索（默认） |
| `plan` | 设计重点 — 在采取行动前询问澄清问题 |
| `ask` | 只读探索 — 无文件修改 |
## 并行执行
通过并行工具调用同时运行多个模型：
```
# 在 Claude Code 中，启动 3 个 Agent 子进程：
Agent 1：cursor_agent，模型=composer-2 → "Review this code"
Agent 2：cursor_agent，模型=cursor/claude-4-sonnet → "Review this code"
Agent 3：cursor_agent，模型=gpt-5.4 → "Review this code"
```
内置信号量（默认：3）队列超出请求，以防止速率限制错误。
## 安全
- **无 shell 执行** — `child_process.spawn` 使用参数数组，防止注入
- **无存储凭证** — cursor-agent 处理其自己的 OAuth
- **无 HTTP 请求** — 纯 CLI 包装，无网络访问超出 cursor-agent
- **进程清理** — AbortSignal 在客户端断开连接或超时时终止子进程
- **自动批准门控** — `--force` 需要显式 `CURSOR_ALLOW_YOLO=true` 环境变量，从不由 LLM 控制
- **并发限制** — 信号量防止资源耗尽
参见 [SECURITY.md](SECURITY.md) 以获取完整详细信息。
## 受监督的编码技能
可选 [Claude Code 技能](https://docs.anthropic.com/en/docs/claude-code)，允许 Claude Code 在任何 Cursor 模型执行编码时充当**监督者**。
**工作原理：** Claude Code 分析任务，向 Cursor 发送精确指令，通过 `cursor_agent`，通过读取磁盘上的实际文件审查输出，并使用 `cursor_reply` 迭代，直到满意（最多 3 轮）。
> **先决条件：** `cursor-cli` MCP 服务器（此软件包）必须先在 Claude Code 中安装和配置。
### 用法
```
/cursor-code <task> # 默认：composer-2
/cursor-code --model gpt-5.4 <task> # 显式模型
/cursor-code --model cursor/grok <task> # 任意 cursor_models 中的模型
```
运行 `cursor_models` 以列出所有可用的模型 ID。
### 安装技能
```bash
mkdir -p ~/.claude/skills/cursor-code
```
创建 `~/.claude/skills/cursor-code/SKILL.md`，内容如下：
<details>
<summary>SKILL.md（点击展开）</summary>
```markdown
---
name: cursor-code
description: 委托任何 Cursor 模型进行编码，同时 Claude Code 监督。
在用户说“cursor-code”、“委托给 cursor”、“cursor code this”或“/cursor-code”时使用。
支持 cursor_models 中的所有模型（Composer 2、GPT 5.4、Gemini 3.1 Pro、Grok 4.20、Claude 4.6 Sonnet、Kimi K2.5 等）。
metadata:
version: 1.0.0
---
# 监督编码：Claude Code（监督者）-> Cursor（编码器）
你是**监督者**（Claude Code）。Cursor 模型是**编码器**。
你给出精确的指令，编码器编写代码，你审查和迭代。
## 解析
从用户输入中提取：
- `--model <id>` -> 要使用的模型（默认：`composer-2`）
- 其他 -> 任务描述
如果用户自然地提到了模型名称（例如“使用 gpt-5.4”，“使用 gemini”，“z grok”），
提取它并映射到 cursor_models ID。
## 工作流程
### 步骤 1：分析
- 读取相关文件以了解当前状态
- 将用户的任务分解为单个、专注的编码指令
- 确定：目标文件、约束、验收标准
### 步骤 2：指令
调用 `cursor_agent`，参数为：
- `model`：提取的模型或 `composer-2`
- `workspace`：当前工作目录
- `prompt`：带有文件路径、函数名称、约束的精确指令
- 保持提示聚焦 — 每次调用一个任务，而不是整个功能
- 从响应中提取并存储 `session_id` 以在步骤 4 中使用
输出前调用： `[cursor-cli -> <model>]`
### 步骤 3：验证
在编码器返回后：
- 运行 `git diff --name-only` 以发现编码器修改的**所有**文件
- 从磁盘读取**所有**修改的文件（使用 Read 工具）— 而不仅仅是 prompt 中的文件
- 与预期进行比较
- 检查：正确性、边缘情况、安全性和类型安全性
### 步骤 4：迭代（最多 3 轮）
如果发现问题：
- 调用 `cursor_reply`，使用相同的 `session_id`
- 提供特定的修复指令（文件：行、问题、操作）
- 在每轮后重新验证
- 如果编码器根本上偏离轨道（错误方法，而不仅仅是小错误），
提前放弃会话并使用更明确的提示重新开始
### 步骤 5：报告
总结给用户：
- 使用的模型（从响应中确认，而不仅仅是请求）
- 已完成的操作
- 修改的文件
- 需要的轮数（1 = 干净，2-3 = 应用纠正）
- Claude Code 直接应用的任何手动修复
## 规则
- 每个 `cursor_agent` 调用**一个**任务 — 不要批量处理整个功能
- **始终**在编码器完成后从磁盘读取文件
- **永远不要**信任缓存的文件内容 — Cursor 直接写入磁盘
- 适当地设置 `timeout_seconds`（典型任务为 30-120 秒）
- 如果任务很简单（< 5 行）— 自己完成，不要委托
- 遵循模型透明度规则 — 在调用前始终显示 `[cursor-cli -> model]`
- 如果 `cursor_agent`/`cursor_reply` 失败（超时、身份验证、未找到 CLI）— 向用户报告错误并运行 `cursor_health` 进行诊断。不要静默重试
- 如果不确定有效的模型 ID — 先调用 `cursor_models`
```
<!-- 技能 v1.0.0 — 与 ~/.claude/skills/cursor-code/SKILL.md 保持同步 -->
</details>
在创建技能文件后重启 Claude Code。
## 开发
```bash
git clone https://github.com/qmediat/cursor-mcp.git
cd cursor-mcp
npm install
npm run build
node dist/index.js
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取指南。
## 许可证
MIT - [Quantum Media Technologies sp. z o.o.](https://www.qmediat.io)
