quota-mcp

English | 简体中文

quota-mcp

AI サブスクリプションアカウントの使用量とクォータを追跡するツールです。各ベンダーのダッシュボードに散在する残高、サブスクリプションの有効期限、レート制限の時間枠を一か所に集約し、REST 管理 API と MCP クエリーインターフェイスの両方から利用できます。エージェント（Hermes、Claude Code など）を設定 1 行で接続すれば、「クォータはあとどれくらい残っていますか？」という質問に自力で回答できます。

現在、2 つのプラットフォームに対応しています。

プラットフォーム	データソース	認証情報	確認できる内容
StepFun（阶跃星辰、.ai は海外向け／.com は中国向け）	platform.stepfun.{ai,com} コンソールの Connect RPC	ブラウザーセッション（Oasis-Token、約 2 時間、自動更新）＋任意のプランキー	プランと有効期限、5 時間／週間／サブスクリプションのクレジット枠、アカウント内のアクセスキー、セッションの状態
Command Code（commandcode.ai）	api.commandcode.ai の未公開 /alpha/* エンドポイント	1 つの Bearer API キー	プラン（GOAT／Pro／Max など）、5 時間／週間／月間の枠、残高、請求期間中のリクエスト統計

主な特長：

• 保存時に暗号化：認証情報は AES-256-GCM で SQLite に暗号化して保存されます（CGO 不要の純粋な Go ドライバー）。すべてのエンドポイントはマスク済みの情報のみを返します
• StepFun セッションの自動更新：バックグラウンド goroutine が 60 秒ごとに確認し、TTL が 20 分未満になったセッションを更新します。期限切れのセッションを更新すると劣化したデバイストークンが発行されるため、それを検出して保存を拒否するガードがあります
• 認証プレーンの分離：StepFun のプランキー（永続）とコンソールセッション（クォータデータ）は別々に管理・検証されます。判定は永続プレーンに基づきます
• MCP は読み取り専用：クエリーインターフェイス（一覧表示／検証／要約）はエージェントに安心して渡せます。登録／更新／削除は REST 側でのみ実行できます
• 単一バイナリで、外部サービスは不要です

クイックスタート

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

起動後：

• http://127.0.0.1:8780/healthz ヘルスチェック
• http://127.0.0.1:8780/api/stepfun/accounts REST 一覧
• http://127.0.0.1:8780/mcp MCP エンドポイント

アカウントの登録

Command Code（2 つの認証プレーン）

alpha/API キープレーンは簡単に利用できます。永続的な Bearer キーを使います。

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"}'

キーは commandcode.ai/settings/keys から取得します（作成時に一度だけ表示されます）。サーバーはまず whoami でキーを検証し、無効なキーは保存しません。

内部／セッションプレーンはブラウザーの動作を再現します。session_text（Cookie: ヘッダー全体、document.cookie のダンプ、または __Secure-commandcode_prod_.session_token の値のみ）を渡してください。billing/credits に対して検証し、合格した場合にのみ保存します。セッションには有効期限があるため、CookieCloud から更新するか、DevTools から再度 Cookie をコピーしてください。

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..."}'

両方が保存されている場合は API キーが優先されます。登録のたびに、渡された認証プレーンが上書きされます。api_key だけを指定して再登録すると、保存済みのセッションは消去され、その逆も同様です。そのため、認証情報のローテーションが意図せずスキップされることはありません。

StepFun（ブラウザーセッション）

Oasis-Token は HttpOnly Cookie のため、document.cookie からは読み取れません。DevTools でリクエストヘッダーからコピーしてください。Cookie: ヘッダー全体（またはトークンのみ）をサーバーに貼り付けます。

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":"[email protected]"}'

実環境でのテストで判明したプロトコルの仕様（すべてコードで対応済み）：

• .ai の Oasis-Token Cookie の値は2 つの JWT を連結したもの（8 セグメント）です。コンソールが受け付けるのは値全体のみで、単一のセグメントでは token is illegal になります
• タイムスタンプの単位はサイトによって異なります。.ai は秒単位の文字列を返し、.com はミリ秒を返します。コードは値の大きさから判定します
• .com のデバイストークンの有効期間は 30 分のみで、RefreshToken は劣化したトークンを返します。.com のセッションは定期的に再インポートする必要があります
• 有効期限が切れた後に更新するとデバイストークンが返され（mode 1、データプレーンでは常に token is illegal になります）、そのため期限切れ前に更新する必要があります。劣化を検出するガードにより、このようなトークンの保存は拒否されます

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 サーフェス（エージェント向け）

接続方法は2つあります。どちらかを選んでください。

1. Streamable HTTP（/mcp で提供）— 常時稼働するデプロイ向け：

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

2. stdio — クライアントがサーバーを自分で起動する場合（Claude Code、コンテナー、mcp-publisher形式のレジストリインストール）：

# 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

Claude Codeやその他のMCPクライアントでも、同じように動作します。

すべてのツールは読み取り専用です。

ツール	説明
quota_list_accounts	すべてのアカウントを一覧表示します。プラン、有効期限、残りのクォータ、セッション／キーの状態（マスク済み）が含まれます
quota_probe_account	1つのアカウントをライブプローブします（上流にアクセスし、数秒かかります）
quota_probe_all	すべてのアカウントを順番にプローブし、キャッシュを更新します
quota_status	概要：プラットフォームごとの稼働中／制限中／無効／再ログインが必要なアカウント数と、アカウントごとの1行のステータス
quota_check_alerts	発報中のアラート：低クォータ、有効期限間近、セッション停止、キー拒否、ウィンドウ超過
quota_report	スケジュール済みダイジェストのペイロード：すべてのアカウント数値と現在のアラート

アラート、有効期限の警告、スケジュール済みダイジェスト

quota-mcp は条件の検出を担います（データを保持し、60秒ごとのバックグラウンドループを実行します）。 スケジュール設定と配信は、利用するエージェントプラットフォームが担います。hermes形式の接続例：

1. しきい値と有効期限のアラート（イベント駆動、プッシュ）

バックグラウンド評価器が古いプローブデータ（5分超）を更新し、ルールを評価して、SQLite（alert_events）で発報中／解決済みの状態機械を管理し、Webhookには状態遷移のみをPOSTします。同じアラートは、解消して再発報されるまで繰り返されません。

ルール：credit_low（残りの割合がしきい値未満）、expiring_soon（サブスクリプション／請求期間がN日以内に終了）、session_dead（StepFunコンソールのセッションを再インポートする必要がある）、key_rejected（Command Codeキーが401／403を返した）、window_limited（レートウィンドウ超過）。

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

状態遷移ごとにプッシュされるペイロード：

{
  "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": []
}

Webhookがなくても問題ありません — hermes（またはその他）からポーリングできます。

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

その後、hermesのcronを15～30分ごとに実行してquota_check_alertsを呼び出し、新しいアラートがあればhermes sendで送信します。GET /api/alerts?history=20も同様です。

2. スケジュール済みダイジェスト（cron）

quota_report（またはGET /api/report）は安定したエージェント向けペイロードを返します。すべてのアカウントのプラン／有効期限／残りのクォータ／セッション状態／ウィンドウ使用量／リクエスト統計と、現在のアラートが含まれます。hermesの既存の09:30 cronをこれに接続すると、1回の実行でツールを呼び出し、メッセージを作成して、hermes sendで配信します。quota-mcp内部でスケジューラーが重複することはありません。

3. 環境変数

変数	デフォルト値	意味
QUOTA_MCP_ALERT_CREDIT_PCT	0.2	残りの割合がこの値を下回ると発報します
QUOTA_MCP_ALERT_EXPIRY_DAYS	7	サブスクリプション／請求期間がN日以内に終了すると発報します
QUOTA_MCP_ALERT_WEBHOOK_URL	—	アラートの状態遷移をPOSTする宛先。空の場合は記録のみ（プルモード）

例（quota_statusの出力 — 「クォータはどのくらい残っていますか？」という質問にエージェントが答えるときに参照する内容）：

{
  "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"]
  }
}

プロジェクト構成

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

セキュリティ境界

• 暗号文はDBにのみ保存されます。ログやレスポンスに出力されることはありません。すべてのエンドポイントはマスクされた値を返します
• RESTサーフェスには書き込み操作が含まれます。ループバックまたはプライベートネットワークにバインドしてください。公開する場合は、リバースプロキシと認証を前段に置き、MCPパスのみを公開してください
• マスターキーを失うと、保存済みのすべての認証情報が読み取れなくなります。QUOTA_MCP_MASTER_KEYをバックアップしてください

リリース

Linux／macOS／Windows（amd64 + arm64）向けのバイナリが、各GitHub Releaseに添付されています。最新バージョンを入手してください。

# 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

イメージは、mainへのプッシュ（:main）およびタグ付け（:v1.0.0、:latest）ごとに、ghcr.io/limitcool/quota-mcp（amd64 + arm64）へ公開されます。

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

同梱のcomposeファイルを使う方法もあります（QUOTA_MCP_MASTER_KEYが必要です。.envに設定してください）。

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

データベースは/dataボリュームに保存されます（QUOTA_MCP_DB=/data/quota-mcp.db）。マスターキーをバックアップしてください。マスターキーを失うと、保存済みのすべての認証情報が読み取れなくなります。

ライセンス

MIT