Cursor Usage

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:

• routing questions through Cursor's questions/options UI (asking is free) instead of open-ended "stop and wait" prompts — so it still asks what it needs, without burning a request. Note: only the question is free; doing the work still consumes your quota,
• batching multiple questions into a single options prompt (one turn instead of many),
• only defaulting silently when the choice is trivial or you didn't answer,
• cutting needless confirmation round-trips ("should I continue?").

When your included quota is used up, get_usage returns exhausted: true. On a corporate/team plan (usage moves to on-demand, covered by the org — not out of your pocket) the agent simply tells you once that the 500 are used up and it's on on-demand, then continues normally — no approval prompts and no more conserving, since there's nothing left to conserve.

How it works (three pieces)

1. Auth (zero-setup by default) — get_usage reconstructs your dashboard session from the token Cursor already stores locally, so on most machines there's nothing to log in to. A browser login flow exists only as a fallback. See Authentication below.
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 calls undocumented internal Cursor endpoints (the same ones your dashboard calls). They can change without notice and may be against Cursor's ToS to script against. Personal, read-only use only.
• The default auth path reads Cursor's local token read-only and never stores it. The optional login fallback stores a session cookie at ~/.cursor-usage/store.json (chmod 600, never committed) that expires periodically — re-run login when that happens.

Setup

cd cursor-usage-mcp
npm install
npx playwright install chromium   # optional: only needed for the browser `login` fallback
npm run build

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. With the default local-token auth there's no login step — just call get_usage.

Authentication

By default the server needs no login. Cursor keeps its own auth in …/Cursor/User/globalStorage/state.vscdb (a SQLite key/value store) under ItemTable → cursorAuth/accessToken — a JWT whose sub claim is your user id. The dashboard's session cookie has a fixed shape:

WorkosCursorSessionToken=<userSub>::<accessToken>

where userSub is the JWT sub with any auth0| prefix stripped. get_usage reads that file read-only (via Node's built-in node:sqlite), rebuilds the exact cookie the browser would send, and also picks up your teamId from cursorAuth/cachedTeam. Nothing is written and the token is never stored. Because the token rotates, it's re-read on every call.

Cross-platform. The state.vscdb location is derived from the OS:

OS	Path
macOS	~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
Windows	%APPDATA%\Cursor\User\globalStorage\state.vscdb
Linux	${XDG_CONFIG_HOME:-~/.config}/Cursor/User/globalStorage/state.vscdb

Override with CURSOR_STATE_DB=/abs/path/state.vscdb for non-standard installs.

When the local path can't be used — the server automatically falls back to the browser login flow. This happens if: the MCP runs on a different machine than Cursor (no local DB), the file isn't readable, node:sqlite is unavailable (Node < 22.5), or you set CURSOR_USAGE_FORCE_LOGIN=1.

Browser login fallback (either works):

# call the `login` tool from inside Cursor (just ask it to "log into cursor-usage")

# — or — standalone CLI flow
npm run login

login opens a real Chromium window (Playwright), sniffs the network to discover the usage endpoints, and saves them plus your session cookie to ~/.cursor-usage/. Run status any time to see which auth source is active (local-token vs login).

For the installing agent — do this right after setup

Agent instructions. If you are an AI agent that just installed or set up this MCP for the user, run one final step before you finish: tell the user which flags/modes are available and ask whether they want to change any. Ask through Cursor's questions/options UI (the same free-to-answer prompt this MCP is built around) — not an open-ended text question. If the MCP is already loaded, call status first so you can show the user their current effective values.

Present these three configurable flags with their current values and let the user pick which (if any) to change in a single options prompt:

Flag	Tool	Env override	Default	What it controls
Conserve threshold	set_threshold	CURSOR_USAGE_THRESHOLD_PCT	0 (always conserve)	The used-% at which conserve mode turns on. 0 = conserve whenever requests remain; 80 = only near the limit.
Verbose	set_verbose	CURSOR_USAGE_VERBOSE	off	Append a Cursor Usage: X/limit · $used/$limit footer to every message.
Follow-up	set_followup	CURSOR_USAGE_FOLLOWUP	off	End each task with a brief "anything else?" question via the options UI.

Suggested options to offer: "Leave defaults", "Raise conserve threshold (e.g. 80%)", "Enable verbose footer", "Enable follow-up questions" — plus room for a custom answer. Apply the chosen changes with the matching set_* tool, then confirm the new effective values with status. (Env vars in mcp.json override the set_* tools — mention this if the user's choice is being overridden by an env value.)

Applying changes to existing chats

New chats pick up the rule and MCP automatically — nothing to do.

For a chat that was already open before you installed/updated this:

1. Reload the MCP once (Settings → MCP → toggle cursor-usage off/on). This restarts the shared server, so every chat — including open ones — sees the latest code and tools on its next turn.

2. Nudge the existing chat so it starts behaving immediately (rules are re-read per turn, but an explicit nudge guarantees it):

   From now on follow the conserve-requests rule: call the cursor-usage get_usage tool,
   report my current usage, and if conserve is on — ask via the questions UI (not open prompts),
   batch questions, and only default on trivial choices.
   If verbose is on, end every message with the footer.
   

Tools

Tool	What it does
get_usage	Reads usage and returns the conserve decision + an exhausted flag (included quota used up → on-demand, corp-covered; agent just notifies once and continues). Call at task start. Includes included-request count, on-demand spend, plan, billing-cycle reset + days left, and a burn-rate projection (requests/day → projected total by reset).
usage_breakdown	This cycle's usage broken down by model: cost, request count, and token totals (input/output/cache). Heavier than get_usage; call on request.
login	Fallback browser login + endpoint auto-discovery (only needed when the local-token path can't be used). Reports current usage immediately.
logout	Clears the stored login session (cookie + endpoints). Does not affect the local-token path. forgetBrowser=true also wipes the saved browser profile.
set_threshold	Sets the persisted threshold (0-100). Default 0 = conserve whenever requests remain. Overridden by the CURSOR_USAGE_THRESHOLD_PCT env var if set.
set_verbose	Enables/disables the per-message usage footer (persisted). Overridden by the CURSOR_USAGE_VERBOSE env var if set.
set_followup	Enables/disables the end-of-task "anything else?" follow-up question (persisted, default off). Overridden by the CURSOR_USAGE_FOLLOWUP env var if set.
status	Shows the active auth source (local-token vs login) and local-token details (state.vscdb path, teamId, token expiry), whether a login session is stored, capture time, and stored/env/effective threshold, verbose, and follow-up settings.

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.

Verbose mode (usage footer on every message)

Set CURSOR_USAGE_VERBOSE to true in the mcp.json env to have the agent append a usage footer to the end of every message:

"env": { "CURSOR_USAGE_VERBOSE": "true" }

Footer format (rendered as a fenced code block):

Cursor Usage: 290/500 requests · $0.00/$75.00 (~as of task start)

You can also toggle it at runtime without editing mcp.json via the set_verbose tool (persisted in ~/.cursor-usage). The CURSOR_USAGE_VERBOSE env var, if set, overrides the tool value — remove it from mcp.json to control verbose purely via set_verbose.

Notes: the numbers reflect the reading from the start of the task (not refreshed per message), and because appending a footer to every message is a model behavior, it may occasionally be missed. Default is off.

Follow-up mode (end-of-task "anything else?" question)

Independent of conserve/verbose. When on, get_usage tells the agent to end each task with a brief follow-up question through Cursor's questions/options UI — e.g. "Anything else?" with a "No, we're done" option plus room for an open answer (a more specific question when it fits). Because answering that UI is free, you almost always get a prompt you can respond to and keep the session going without spending an extra request to re-engage.

Enable via env in mcp.json:

"env": { "CURSOR_USAGE_FOLLOWUP": "true" }

Or toggle at runtime with the set_followup tool (persisted in ~/.cursor-usage). The CURSOR_USAGE_FOLLOWUP env var, if set, overrides the tool value. Default is off.

Threshold, continued

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 requests (with the cookie from the local token, or the stored login cookie) to the dashboard endpoints:

• /api/usage?user=<sub> → included-request count (gpt-4.numRequests / maxRequestUsage), e.g. 278/500.
• /api/usage-summary → membershipType, isUnlimited, limitType, on-plan spend (individualUsage.plan.used), and on-demand spend (individualUsage.onDemand, cents → dollars).
• /api/dashboard/teams (team accounts) → requestQuotaPerSeat.
• /api/dashboard/get-hard-limit (team accounts) → per-user $ cap for context.

The browser (Playwright) is used only during the login fallback. 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.

Team accounts. For team-billed accounts the included-request math mirrors Cursor's dashboard exactly: the limit is 500 × requestQuotaPerSeat (fetched from /api/dashboard/teams) and the used count comes from on-plan spend (ceil(planUsedCents / 4)), falling back to the legacy gpt-4 bucket when spend is 0 or the seat quota can't be read. Individual accounts just use the legacy gpt-4 bucket directly.

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