cursor-usage-mcp

Purpose: stop the Cursor agent from burning through your request quota.

On many Cursor plans you get a fixed pool of included requests (e.g. 500 / month) and then pay per request out of a budget. Every time the agent stops mid-task to ask you a one-off question, your answer starts a new billable turn — so a chatty agent quietly eats your quota.

This is a local MCP server that fixes that. It reads your live usage from the same backend your Cursor dashboard uses, and hands the agent a conserve flag. When you're consuming your quota, a bundled rule makes the agent conserve requests by:

• batching all clarifying questions into a single prompt (one turn instead of many),

• preferring sensible defaults and proceeding instead of stopping to ask,

• cutting needless confirmation round-trips ("should I continue?").

How it works (three pieces)

1. login (one-time) — opens a browser via Playwright, you log into Cursor, and it captures your session cookie + auto-discovers the usage endpoints, storing them at ~/.cursor-usage/.

2. get_usage — makes a direct authenticated API call (no browser) and returns your included-request usage (e.g. 278/500), on-demand spend ($0/$75), and a conserve decision computed against a threshold.

3. conserve-requests rule (installed globally) — tells the agent to call get_usage at the start of each task and follow the conserve behavior above when the flag is on.

The threshold controls when conserving kicks in: 0 (default) = conserve whenever you still have requests; 80 = only conserve once you've used 80% of the quota. See Tuning below.

Heads up / caveats

• This scrapes an undocumented internal Cursor endpoint (the same one your dashboard calls). It can change without notice and may be against Cursor's ToS to script against. Personal, read-only use only.

• Your session cookie is stored locally at ~/.cursor-usage/store.json (chmod 600) and is never committed. It expires periodically — just re-run login when that happens.

How it works

1. login opens a real Chromium window (via Playwright). You log in to Cursor normally and open your usage/dashboard page. While the page loads, the server sniffs the network, finds the JSON endpoint that returns your usage numbers, and saves both that endpoint and your session cookie to ~/.cursor-usage/.

2. get_usage replays that request with your stored cookie, parses out used / limit / usedPct, and returns a conserve flag based on your activationThresholdPct.

3. A globally-installed rule (~/.cursor/rules/conserve-requests.mdc) tells the agent to call get_usage at the start of each task and follow the conserve policy when the flag is on.

Related MCP server: mcp-token-saver

Setup

cd cursor-usage-mcp
npm install
npx playwright install chromium   # one-time: downloads the browser Playwright drives
npm run build

First-time login (either works):

# call the `login` tool from inside Cursor once the MCP is loaded (Simply by asking log into cursor-usage)

# — or — standalone CLI flow
npm run login

The server is already registered in ~/.cursor/mcp.json as cursor-usage. Restart Cursor (or reload the MCP) after npm run build so it picks up dist/index.js.

Tools

Tuning when conserve mode kicks in

The threshold is the minimum used percentage at which conserve mode activates:

• 0 (default): conserve as long as any requests remain.

• 80: only conserve once you've used ≥80% of the limit.

There are two ways to set it, and the env var wins if both are set:

1. Env var (recommended — declarative, in mcp.json):

"cursor-usage": {
  "command": "node",
  "args": ["/ABSOLUTE/PATH/TO/cursor-usage-mcp/dist/index.js"],
  "env": {
    "CURSOR_USAGE_THRESHOLD_PCT": "80"
  }
}

Change the number and reload the MCP. Accepts 0–100. Leave it as "0" (or remove it) for the default always-conserve behavior. If CURSOR_USAGE_THRESHOLD_PCT is set, it overrides any value set via the tool below.

2. set_threshold tool (persisted in ~/.cursor-usage):

set_threshold { "activationThresholdPct": 80 }

Used only when the env var is unset/empty. Run status to see storedThresholdPct, envThresholdPct, and the resulting effectiveThresholdPct.

How usage is read (no browser at query time)

get_usage does not open a browser. It makes direct authenticated GET requests (with your stored cookie) to the two reliable dashboard endpoints:

• /api/usage → included-request count (gpt-4.numRequests / maxRequestUsage), e.g. 278/500.

• /api/usage-summary → membershipType, isUnlimited, and on-demand spend (individualUsage.onDemand, cents → dollars).

The browser (Playwright) is used only during login to capture your session cookie and discover these endpoints. The conserve decision is based on the included-request percentage (the "X / 500" number).

Budget vs. team cap. The spend line reports your actual on-demand budget from individualUsage.onDemand.limit (authoritative for you), and — for context — the team-wide default per-user cap from get-hard-limit (hardLimitPerUser). These usually match, but can differ if your org sets per-user overrides; the tool flags it when they diverge.

get_usage always returns the raw JSON per source, so if a field ever looks off you can inspect raw and adjust parseIncludedRequests / parseSummary in src/usage.ts.