Skip to main content
Glama

English | 简体中文

quota-mcp

A usage & quota tracker for AI subscription accounts. It pulls the balances, subscription expiry dates and rate-limit windows that are scattered across vendor dashboards into one place, and exposes them through both a REST management API and an MCP query surface — point your agent (Hermes, Claude Code, …) at it with one config line and it can answer "how much quota do I have left?" on its own.

Two platforms supported today:

Platform

Data source

Credential

What you can see

StepFun (阶跃星辰, .ai intl / .com China)

platform.stepfun.{ai,com} console Connect RPC

Browser session (Oasis-Token, ~2 h, auto-renewed) + optional plan key

Plan & expiry, 5-hour / weekly / subscription credit windows, access keys under the account, session health

Command Code (commandcode.ai)

Undocumented /alpha/* endpoints on api.commandcode.ai

A single Bearer API key

Plan (GOAT/Pro/Max/…), 5-hour / weekly / monthly windows, balances, billing-period request stats

Highlights:

  • Encrypted at rest: credentials are AES-256-GCM encrypted into SQLite (pure-Go driver, no CGO); every endpoint returns masked views only

  • StepFun session auto-renewal: a background goroutine checks every 60 s and renews any session whose TTL drops below 20 min. Renewing an expired session gets you a degraded device token — there is a guard that detects this and refuses to persist it

  • Dual auth planes: StepFun's plan key (permanent) and console session (quota data) are managed and probed separately; the verdict is driven by the permanent plane

  • MCP is read-only: the query surface (list / probe / summarize) is safe to hand to agents; enrol / renew / delete live on the REST side only

  • Single binary, zero external services

Quick start

go build -o quota-mcp ./cmd/quota-mcp

# In production set the master key explicitly (64 hex chars). Without it the key is
# derived from machine traits and old ciphertext becomes unreadable after a migration.
export QUOTA_MCP_MASTER_KEY=$(openssl rand -hex 32)

./quota-mcp -db data/quota-mcp.db -listen 127.0.0.1:8780

After startup:

  • http://127.0.0.1:8780/healthz health check

  • http://127.0.0.1:8780/api/stepfun/accounts REST list

  • http://127.0.0.1:8780/mcp MCP endpoint

Related MCP server: agent-budget

Enrolling accounts

Command Code (two credential planes)

The alpha/API-key plane is the easy one — a permanent Bearer key:

curl -X POST http://127.0.0.1:8780/api/commandcode/accounts \
  -H 'Content-Type: application/json' \
  -d '{"service":"cc-myname","api_key":"user_xxx","label":"primary"}'

Get the key from commandcode.ai/settings/keys (shown once at creation). The server validates it with whoami first and refuses to store a rejected key.

The internal/session plane mirrors the browser: pass session_text (the whole Cookie: header, a document.cookie dump, or the bare __Secure-commandcode_prod_.session_token value). It is validated against billing/credits and never stored unless it passes. Sessions expire, so refresh them from CookieCloud or by copying the cookie again from DevTools:

curl -X POST http://127.0.0.1:8780/api/commandcode/accounts \
  -H 'Content-Type: application/json' \
  -d '{"service":"cc-myname","session_text":"__Secure-commandcode_prod_.session_token=eyJ..."}'

When both are stored the API key wins. Each enrol overwrites the credential planes it was given — re-enrolling with only api_key clears any stored session, and vice-versa, so a rotation is never silently skipped.

StepFun (browser session)

Oasis-Token is an HttpOnly cookie, so document.cookie cannot read it — copy it from a request header in DevTools. Paste the whole Cookie: header (or the bare token) to the server:

curl -X POST http://127.0.0.1:8780/api/stepfun/accounts \
  -H 'Content-Type: application/json' \
  -d '{"service":"ai-412848664332275712","region":"ai","session_text":"Oasis-Token=eyJ...; Oasis-Webid=...","email":"me@example.com"}'

Protocol findings from real-world testing (all handled in code):

  • The .ai Oasis-Token cookie value is two JWTs concatenated (8 segments); the console only accepts the whole value — a single segment gets you token is illegal

  • Timestamp units differ per site: .ai returns second-level strings, .com returns milliseconds; the code infers by magnitude

  • .com device tokens live only 30 minutes and its RefreshToken returns a degraded token — .com sessions need periodic re-import

  • Renewing after expiry yields a device token (mode 1, data plane always token is illegal), so renewal must happen before expiry; a degradation guard refuses to store such tokens

REST API

GET    /api/stepfun/accounts                     List (masked view)
POST   /api/stepfun/accounts                     Enrol/update (stored only if at least one plane probes OK)
POST   /api/stepfun/accounts/{service}/probe     Probe (auto-renews once on console auth failure)
POST   /api/stepfun/accounts/{service}/renew     Force-renew the console session
POST   /api/stepfun/accounts/{service}/register?region=ai   Register an anonymous device slot (self-test)
DELETE /api/stepfun/accounts/{service}           Delete
POST   /api/stepfun/probe                        Probe all (cron-friendly)

GET    /api/commandcode/accounts                 List (masked view)
POST   /api/commandcode/accounts                 Enrol/update (api_key or session_text; stored only if it probes OK)
POST   /api/commandcode/accounts/{service}/probe Probe
DELETE /api/commandcode/accounts/{service}       Delete
POST   /api/commandcode/probe                    Probe all

MCP surface (for agents)

Two ways to connect — pick either:

1. Streamable HTTP (served on /mcp) — for always-on deployments:

mcp_servers:
  quota:
    url: http://<your-host>:8780/mcp

2. stdio — for clients that spawn the server themselves (Claude Code, containers, mcp-publisher-style registry installs):

# local binary
quota-mcp -stdio

# or straight from the published image (works with zero setup)
docker run -i --rm -v quota-mcp-data:/data ghcr.io/limitcool/quota-mcp:latest

Works the same way from Claude Code or any other MCP client.

All tools are read-only:

Tool

Description

quota_list_accounts

List every account: plan, expiry, remaining quota, session/key status (masked)

quota_probe_account

Live-probe one account (hits upstream, takes a few seconds)

quota_probe_all

Serially probe all accounts and refresh the cache

quota_status

Summary: per-platform counts of serving / limited / invalid / needs-relogin, plus a one-line status per account

quota_check_alerts

Firing alerts: low quota, upcoming expiry, dead session, rejected key, window exceeded

quota_report

The scheduled-digest payload: all account numbers + current alerts

Alerts, expiry warnings & scheduled digest

quota-mcp owns condition detection (it holds the data and runs a 60 s background loop); scheduling and delivery belong to your agent platform. A hermes-style wiring:

1. Threshold & expiry alerts (event-driven, push)

A background evaluator refreshes stale probe data (>5 min), evaluates rules, keeps a firing/resolved state machine in SQLite (alert_events), and POSTs only the transitions to a webhook — the same alert never repeats until it clears and fires again.

Rules: credit_low (remaining share below threshold), expiring_soon (subscription/billing period ending within N days), session_dead (StepFun console session needs re-import), key_rejected (Command Code key got 401/403), window_limited (rate window exceeded).

QUOTA_MCP_ALERT_WEBHOOK_URL=http://<hermes>:8642/webhooks/quota \
QUOTA_MCP_ALERT_CREDIT_PCT=0.2 \
QUOTA_MCP_ALERT_EXPIRY_DAYS=7 \
./quota-mcp -listen 0.0.0.0:8780

Payload pushed on each transition:

{
  "source": "quota-mcp",
  "at": "2026-09-21T15:52:30Z",
  "fired":    [{"kind":"credit_low","provider":"stepfun","service":"ai-…","severity":"warn","title":"订阅额度即将耗尽","detail":"剩余 13%(阈值 20%),2026-10-20 重置"}],
  "resolved": []
}

No webhook? No problem — hermes (or anything) can poll instead:

# hermes mcp_servers
mcp_servers:
  quota:
    url: http://<host>:8780/mcp

then have a hermes cron every 15–30 min call quota_check_alerts and hermes send anything new. Same for GET /api/alerts?history=20.

2. Scheduled digest (cron)

quota_report (or GET /api/report) returns a stable, agent-friendly payload: every account's plan / expiry / remaining quota / session state / window usage / request stats, plus current alerts. Point hermes's existing 09:30 cron at it: one turn calls the tool, composes the message, and delivers via hermes send. No scheduler is duplicated inside quota-mcp.

3. Environment variables

Variable

Default

Meaning

QUOTA_MCP_ALERT_CREDIT_PCT

0.2

Fires when remaining share drops below this

QUOTA_MCP_ALERT_EXPIRY_DAYS

7

Fires when subscription/billing period ends within N days

QUOTA_MCP_ALERT_WEBHOOK_URL

—

POST target for alert transitions; empty = record only (pull mode)

Example (quota_status output — what an agent would read to answer "how much quota is left?"):

{
  "stepfun": {
    "total": 2, "healthy": 2, "attention": 0,
    "accounts": ["ai-4128…: ok (10 models)", "com-3766…: ok (0 models)"]
  },
  "commandcode": {
    "total": 1, "serving": 1, "limited": 0, "key_rejected": 0,
    "accounts": ["cc-limitcool: serving GOAT"]
  }
}

Project layout

cmd/quota-mcp/        Entrypoint (flags/env config, one port serving both surfaces)
internal/store/       SQLite + AES-256-GCM encryption + schema
internal/stepfun/     StepFun protocol client + account registry + background renewer
internal/commandcode/ Command Code protocol client + account registry
internal/api/         REST management surface (net/http, no framework)
internal/mcpsrv/      MCP query surface (modelcontextprotocol/go-sdk)
internal/alerts/      Alert rules + firing/resolved state machine + webhook push
internal/digest/       Scheduled-digest payload for cron consumers

Security boundary

  • Ciphertext goes to the DB only — never to logs, never to responses; every endpoint returns masks

  • The REST surface contains writes: bind it to loopback or a private network. To expose it publicly, front it with a reverse proxy + auth and only publish the MCP path

  • Losing the master key means every stored credential becomes unreadable — back up QUOTA_MCP_MASTER_KEY

Releases

Binaries for Linux / macOS / Windows (amd64 + arm64) are attached to each GitHub Release. Grab the latest:

# example: linux amd64
curl -LO https://github.com/limitcool/quota-mcp/releases/latest/download/quota-mcp_linux_amd64
chmod +x quota-mcp_linux_amd64

Docker

Image is published to ghcr.io/limitcool/quota-mcp (amd64 + arm64) on every main push (:main) and tag (:v1.0.0, :latest).

docker run -d --name quota-mcp \
  -p 8780:8780 \
  -v quota-mcp-data:/data \
  -e QUOTA_MCP_MASTER_KEY=$(openssl rand -hex 32) \
  ghcr.io/limitcool/quota-mcp:latest

Or with the bundled compose file (QUOTA_MCP_MASTER_KEY is required, put it in .env):

echo "QUOTA_MCP_MASTER_KEY=$(openssl rand -hex 32)" > .env
docker compose up -d

The database lives in the /data volume (QUOTA_MCP_DB=/data/quota-mcp.db). Back up the master key — losing it makes every stored credential unreadable.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Budget management and cost tracking MCP server for autonomous agents, enabling budget creation, cost recording, spending projections, and alert rules.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Surface Claude Code token usage, estimated cost, and plan-limit status in any MCP client. Enables agents to query usage data from local logs and Anthropic API.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude Code sessions to check account rate-limit headroom, local token spend, and live session status, with read-only MCP tools for limits, summaries, token usage, and session listing.
      2
      MIT