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 · CURSOR_MCP_PROPOSAL.md

---

Quick start

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

{
  "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

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. Never commit real keys.

---

Fritz task

Scheduled coworker_cursor_spend_watch — every 2 hours, emails on warn or critical.

See docs/FRITZ_INTEGRATION.md.

---

MCPB (Claude Desktop)

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. Current: v0.2.0 (2026-06-07) — cursor_inbox + MCPB packaging.