Content
# cursor-mcp
**FastMCP 3.2** server for Cursor **platform APIs** — spend guardrails, cloud agent monitoring, and inter-agent inbox.
Complements **cursor-app-control** (IDE/Glass). Does not replace it.
| Port | Role |
|------|------|
| **11000** | HTTP `/mcp` (Fritz `fleet_bridge`) |
| stdio | Cursor `mcp.json` / Claude Desktop |
**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)
---
## Quick start
```powershell
cd D:\Dev\repos\cursor-mcp
Copy-Item .env.example .env
# Edit .env — set CURSOR_API_KEY (and CURSOR_ADMIN_API_KEY for full spend 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_..."
}
}
}
}
```
---
## Tools
### `cursor_usage`
| Operation | Purpose |
|-----------|---------|
| `alert_check` | **Main guardrail** — hourly spend, on-demand, running cloud agents, cache delta |
| `summary` | One-shot dashboard replacement |
| `spend` | Admin API `/teams/spend` row |
| `events` | Last N hours usage events (sum `chargedCents`) |
| `limits` | Show configured thresholds |
| `me` | API key identity |
### `cursor_cloud`
| Operation | Purpose |
|-----------|---------|
| `list` | All cloud agents — spot runaway parallelism |
| `status` | Single agent |
| `runs` | Runs for agent |
| `cancel` | Cancel a run (use sparingly) |
### `cursor_inbox`
Structured message drop for Cursor agents. Any process posts; agent polls at task start.
| Operation | Purpose |
|-----------|---------|
| `post` | Drop a message (subject, body, priority, tags, optional payload dict) |
| `list` | Poll unread — call at agent task start |
| `read` | Full message by id |
| `ack` | Acknowledge (moves to `inbox/acked/`) |
| `ack_all` | Acknowledge all unread |
| `purge` | Delete acked messages older than N days |
**Drop dir:** `CURSOR_INBOX_DIR` env (default `~/.cursor-mcp/inbox/`). No daemon, no network — pure JSON files.
**Who can write:**
- Claude Desktop: `cursor_inbox post` (add cursor-mcp to Claude Desktop MCP config)
- meta_mcp / any fleet server: direct JSON file drop to `CURSOR_INBOX_DIR`
- PowerShell / Python scripts: same
- Sandra: `cursor_inbox post` from any MCP client
**Cursor agent convention:** add `cursor_inbox list` to AGENTS.md or Cursor rules so agents check for messages at the start of every session.
### `cursor_docs`
Fleet snippets. Topics: `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`
Read-only SDK guidance (no agent spawn): `capabilities`, `upgrade_notes`, `autoreview_template`, `custom_tools_guide`, `store_options`.
Starter permissions: [docs/permissions.fleet.example.json](docs/permissions.fleet.example.json)
### `cursor_help`
Tool index and setup. Always current.
---
## Auth notes
| Key | Endpoints |
|-----|-----------|
| `CURSOR_API_KEY` | `/v1/me`, `/v1/agents/*` |
| `CURSOR_ADMIN_API_KEY` | `/teams/spend`, `/teams/filtered-usage-events` |
**Individual Pro** without Admin API: `alert_check` still works via cloud agent count + cache; spend/events show `partial_errors` until you add a team admin key.
Poll **at most every 1–2 hours** — Admin API aggregates hourly.
---
## Env
| Variable | Default | Purpose |
|----------|---------|---------|
| `CURSOR_API_KEY` | — | User key, required |
| `CURSOR_ADMIN_API_KEY` | — | Team admin key, optional |
| `CURSOR_MCP_HOST` | `127.0.0.1` | HTTP bind |
| `CURSOR_MCP_PORT` | `11000` | HTTP port |
| `CURSOR_INBOX_DIR` | `~/.cursor-mcp/inbox/` | Message drop dir |
| `CURSOR_HOURLY_SPEND_WARN_CENTS` | `300` | ~$3/h warn |
| `CURSOR_ON_DEMAND_WARN_CENTS` | `2000` | ~$20 on-demand warn |
| `CURSOR_RUNNING_AGENTS_WARN` | `3` | Parallel agents warn |
| `CURSOR_USAGE_EMAIL` | — | Filter spend by email |
Copy [.env.example](.env.example). Never commit real keys.
---
## Fritz task
Scheduled **`coworker_cursor_spend_watch`** — every **2 hours**, emails on `warn` or `critical`.
See [docs/FRITZ_INTEGRATION.md](docs/FRITZ_INTEGRATION.md).
---
## MCPB (Claude Desktop)
```powershell
uv sync
just mcpb-pack
# → dist/cursor-mcp-v0.2.0.mcpb — drag into Claude Desktop Extensions
```
Requires `uv` on PATH. Set `CURSOR_API_KEY` / `CURSOR_ADMIN_API_KEY` in the extension env.
---
## Changelog
See [CHANGELOG.md](CHANGELOG.md). Current: **v0.2.0** (2026-06-07) — `cursor_inbox` + MCPB packaging.
