cursor-usage-optimizer

cursor-usage-optimizer

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) this is internal info for the agent only: it silently continues normally — no approval prompts, no more conserving, and crucially no "you're out of requests" reminders or usage/spend numbers volunteered to you (that's transparent). The only place usage surfaces is the verbose footer, and only when verbose is on.

Usage cache. Once exhausted, the decision can't change until the billing cycle resets (used only goes up), so get_usage serves a cached reading instead of hitting the network on every task — turning a ~1s call into a ~10ms read. The cache lives in ~/.cursor-usage/cache.json, auto-invalidates at the cycle's billingCycleEnd (from the API), and refreshes at most once/day as a safety net. Below the limit it always fetches fresh (crossing the threshold matters). Verbose isn't affected — the footer has its own non-blocking background refresher that shares the same cache. Pass refresh: true to get_usage, or login/logout, to force a fresh read.

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

Install via npm (recommended)

No clone, no build. Add it to ~/.cursor/mcp.json and let npx fetch it:

{
  "mcpServers": {
    "cursor-usage": {
      "command": "npx",
      "args": ["-y", "cursor-usage-optimizer"],
      "env": {
        "CURSOR_USAGE_THRESHOLD_PCT": "0",
        "CURSOR_USAGE_VERBOSE": "false",
        "CURSOR_USAGE_FOLLOWUP": "false"
      }
    }
  }
}

Requires Node ≥ 22.5 (uses the built-in node:sqlite). Reload Cursor — with the default local-token auth there's no login step, just call get_usage.

Optionally install the flag-aware self-check hook (adds a postToolUse entry to ~/.cursor/hooks.json):

npx -y -p cursor-usage-optimizer cursor-usage-optimizer-install-hook

From source (contributors)

git clone https://github.com/udah1/cursor-usage-mcp && cd cursor-usage-mcp
npm install
npx playwright install chromium   # optional: only needed for the browser `login` fallback
npm run build

Then point mcp.json at the local build ("command": "node", "args": ["/ABS/PATH/dist/index.js"]) and set CURSOR_USAGE_MCP_DIR to the repo path so the hook uses your local build. Restart Cursor (or reload the MCP) after npm run build.

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.

Version updates (daily check)

The server checks once a day, in the background, whether a newer version exists. It auto-detects how it was installed:

• npm install (no .git): compares the installed version against the latest dist-tag on the npm registry.
• git checkout (.git present): compares local HEAD against origin/master via GitHub's compare API (no git fetch).

Both are fully fail-open (offline / proxy / rate-limit simply surfaces nothing) and run from the background reminder refresher (plus a non-blocking kick from get_usage), so they never add latency.

When an update is available, get_usage returns update.available: true and the agent asks you once, via the options UI, whether to update. If you skip, dismiss_update records that version so you're not asked again until an even newer version appears (not daily). If you accept, the agent gives you the right commands for your install (reload the MCP so npx fetches @latest, or git pull && npm run build for a clone). State lives in ~/.cursor-usage/update.json. Run check_update any time to check immediately.

Reminder hook (flag-aware self-check)

hooks/cursor-usage-optimizer-reminder.sh is an optional postToolUse hook that periodically re-injects a short self-check so long chats keep following the rules. Install it with:

npx -y -p cursor-usage-optimizer cursor-usage-optimizer-install-hook

This copies the script to ~/.cursor/hooks/ and adds the postToolUse entry to ~/.cursor/hooks.json (replacing any older cursor-usage reminder entry). The installed hook works for both install modes: if CURSOR_USAGE_MCP_DIR points at a built local clone it uses that, otherwise it refreshes via npx -y -p cursor-usage-optimizer cursor-usage-optimizer-reminder.

It's flag-aware: reminder-cli builds the text from the current state, so it only mentions modes that are actually active — e.g. once the quota is exhausted it drops the CONSERVE nudge (nothing left to conserve), and it omits FOLLOW-UP unless follow-up mode is on. The refresh runs detached (non-blocking) and shares the usage cache.

Because the hook launches the CLIs without the MCP's env, the MCP syncs the effective config (env-aware verbose/followup/threshold) into ~/.cursor-usage/store.json on startup, so the hook-run CLIs read the same settings you configured via mcp.json.

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; the agent silently continues, no reminders/numbers). 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.
check_update	Forces an immediate check against GitHub for a newer version (bypasses the once/day throttle) and reports how to update.
dismiss_update	Records that the user declined the current available update, so it isn't surfaced again until a newer version lands.
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": "npx",
  "args": ["-y", "cursor-usage-optimizer"],
  "env": {
    "CURSOR_USAGE_THRESHOLD_PCT": "80"
  }
}

(For a local clone, use "command": "node", "args": ["/ABS/PATH/dist/index.js"] instead.)

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.

Releasing (maintainers)

Publishing to npm is automated via GitHub Actions (.github/workflows/release.yml) and triggered by a version tag:

npm version patch      # bumps package.json + creates a vX.Y.Z tag (use minor/major as needed)
git push --follow-tags # pushes the commit and the tag → CI publishes to npm

The workflow runs npm ci && npm run build, verifies the tag matches package.json's version, then npm publish --access public.

Auth = npm Trusted Publishing (OIDC) — no token/secret. The workflow authenticates with GitHub's OIDC token (id-token: write); provenance is generated automatically. One-time setup on npmjs.com: package → Settings → Publishing access → Trusted Publisher → GitHub Actions, and enter:

Field	Value
Organization or user	udah1
Repository	cursor-usage-mcp
Workflow filename	release.yml
Environment	(leave blank)

(The workflow upgrades npm to @latest in CI because Trusted Publishing needs npm ≥ 11.5.1.)