内容
# cursor-mcp
**FastMCP 3.2** 服务器，用于 Cursor **平台 API** — 支出防护、云代理监控和代理间收件箱。
补充 **cursor-app-control** (IDE/Glass)。不会取代它。
| 端口 | 角色 |
|------|------|
| **11000** | HTTP `/mcp` (Fritz `fleet_bridge`) |
| 标准输入/输出 | Cursor `mcp.json` / Claude 桌面版 |
**MCD:** [CHANGELOG_DIGEST_JUN_2026.md](../mcp-central-docs/ecosystem/cursor/CHANGELOG_DIGEST_JUN_2026.md) · [CURSOR_MCP_PROPOSAL.md](../mcp-central-docs/ecosystem/cursor/CURSOR_MCP_PROPOSAL.md)
---
## 快速开始
```powershell
cd D:\Dev\repos\cursor-mcp
Copy-Item .env.example .env
# 编辑 .env — 设置 CURSOR_API_KEY （和 CURSOR_ADMIN_API_KEY 以获取完整的支出 API）
uv sync
.\start.ps1 -Serve
```
### Cursor `mcp.json`
```json
{
"mcpServers": {
"cursor-mcp": {
"command": "D:\\Dev\\repos\\cursor-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "cursor_mcp", "--stdio"],
"env": {
"CURSOR_API_KEY": "cursor_...",
"CURSOR_ADMIN_API_KEY": "crsr_..."
}
}
}
}
```
---
## 工具
### `cursor_usage`
| 操作 | 目的 |
|-----------|---------|
| `alert_check` | **主要防护** — 每小时支出、按需、运行云代理、缓存增量 |
| `summary` | 一次性仪表盘替代 |
| `spend` | 管理 API `/teams/spend` 行 |
| `events` | 最后 N 小时使用事件（求和 `chargedCents`） |
| `limits` | 显示配置的阈值 |
| `me` | API 密钥身份 |
### `cursor_cloud`
| 操作 | 目的 |
|-----------|---------|
| `list` | 所有云代理 — 查找失控的并行处理 |
| `status` | 单个代理 |
| `runs` | 代理运行 |
| `cancel` | 取消运行（谨慎使用） |
### `cursor_inbox`
Cursor 代理的结构化消息投递。任何进程都可以投递；代理在任务开始时轮询。
| 操作 | 目的 |
|-----------|---------|
| `post` | 投递消息（主题、正文、优先级、标签、可选有效载荷字典） |
| `list` | 轮询未读消息 — 在代理任务开始时调用 |
| `read` | 按 ID 读取完整消息 |
| `ack` | 确认（移动到 `inbox/acked/`） |
| `ack_all` | 确认所有未读消息 |
| `purge` | 删除已确认的老消息（N 天前） |
**投递目录：** `CURSOR_INBOX_DIR` 环境变量（默认为 `~/.cursor-mcp/inbox/`）。无守护进程，无网络 — 纯 JSON 文件。
**谁可以写入：**
- Claude 桌面版：`cursor_inbox post`（将 cursor-mcp 添加到 Claude 桌面版 MCP 配置）
- meta_mcp / 任意 Fleet 服务器：直接将 JSON 文件投递到 `CURSOR_INBOX_DIR`
- PowerShell / Python 脚本：相同
- Sandra：`cursor_inbox post` 从任意 MCP 客户端
**Cursor 代理约定：** 在 AGENTS.md 或 Cursor 规则中添加 `cursor_inbox list`，以便代理在每次会话开始时检查消息。
### `cursor_docs`
Fleet 代码片段。主题：`cloud-agents`、`profiles`、`mcp-config`、`spend-guardrails`、`cursor-mcp`、`cursor-inbox`、`sdk-jun-2026`、`design-mode`、`auto-review`、`context-canvas`、`changelog-jun-2026`。
### `cursor_sdk`
只读 SDK 指南（无代理生成）：`capabilities`、`upgrade_notes`、`autoreview_template`、`custom_tools_guide`、`store_options`。
启动权限：[docs/permissions.fleet.example.json](docs/permissions.fleet.example.json)
### `cursor_help`
工具索引和设置。始终保持最新。
---
## 认证说明
| 密钥 | 端点 |
|-----|-----------|
| `CURSOR_API_KEY` | `/v1/me`、`/v1/agents/*` |
| `CURSOR_ADMIN_API_KEY` | `/teams/spend`、`/teams/filtered-usage-events` |
**个人专业版** 无管理员 API：`alert_check` 仍然通过云代理计数 + 缓存有效；支出/事件显示 `partial_errors`，直到您添加团队管理员密钥。
**最多每 1-2 小时** 轮询一次 — 管理员 API 聚合每小时数据。
---
## 环境变量
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `CURSOR_API_KEY` | — | 用户密钥，必填 |
| `CURSOR_ADMIN_API_KEY` | — | 团队管理员密钥，可选 |
| `CURSOR_MCP_HOST` | `127.0.0.1` | HTTP 绑定 |
| `CURSOR_MCP_PORT` | `11000` | HTTP 端口 |
| `CURSOR_INBOX_DIR` | `~/.cursor-mcp/inbox/` | 消息投递目录 |
| `CURSOR_HOURLY_SPEND_WARN_CENTS` | `300` | ~$3/小时 警告 |
| `CURSOR_ON_DEMAND_WARN_CENTS` | `2000` | ~$20 按需警告 |
| `CURSOR_RUNNING_AGENTS_WARN` | `3` | 并行代理警告 |
| `CURSOR_USAGE_EMAIL` | — | 按电子邮件筛选支出 |
复制 [.env.example](.env.example)。永远不要提交真实密钥。
---
## Fritz 任务
计划的 **`coworker_cursor_spend_watch`** — 每 **2 小时**，在 `warn` 或 `critical` 时发送电子邮件。
参见 [docs/FRITZ_INTEGRATION.md](docs/FRITZ_INTEGRATION.md)。
---
## MCPB（Claude 桌面版）
```powershell
uv sync
just mcpb-pack
# → dist/cursor-mcp-v0.2.0.mcpb — 拖入 Claude 桌面版扩展
```
需要 `uv` 在 PATH 中。 在扩展环境中设置 `CURSOR_API_KEY` / `CURSOR_ADMIN_API_KEY`。
---
## 更新日志
参见 [CHANGELOG.md](CHANGELOG.md)。当前：**v0.2.0**（2026-06-07）— `cursor_inbox` + MCPB 打包。
