quota-mcp

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:

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

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:

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

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