minimax-remaining-mcp

MCP-Server: Damit KI-Agenten wissen, wie viel Kontingent im MiniMax Token Plan noch übrig ist, und wann sie sich selbst pausieren sollten, um Ratenbegrenzungen zu vermeiden.

Kompatibel mit DeepSeek Harness (DSH), Claude Desktop, Cursor und allen anderen Clients, die das MCP-Protokoll unterstützen.

┌──────────────┐    stdio    ┌──────────────────────┐   HTTPS   ┌──────────────┐
│   AI 代理   │ ──────────► │  minimax-remaining-  │ ────────► │  MiniMax     │
│ (DSH 等)    │ ◄────────── │         mcp          │ ◄──────── │   Web API    │
└──────────────┘             └──────────┬───────────┘           └──────────────┘
                                        │
                                        ▼
                                 ┌─────────────┐
                                 │  Camoufox   │  一次性手动登录
                                 │  (Firefox)  │  → 持久化会话 cookie
                                 └─────────────┘

Projektübersicht

Das Panel "5h-Limit / 61% verbraucht / Reset in 2h56m" der MiniMax-Webkonsole wird von zwei HTTP-Endpunkten gespeist:

1. /v1/api/openplatform/coding_plan/remains?GroupId=… — Restprozentsatz + Countdown für das feste 5-Stunden-Fenster

2. /backend/account/token_plan_credit — Kumuliertes Kontingent des Tarifpools (wöchentlich)

Beide Endpunkte akzeptieren den api_key der Weboberfläche (sieht aus wie sk-cp-...) nicht als Bearer-Token – die Verwendung führt zu base_resp = {2062, "no active token plan"}. Der einzige funktionierende Ansatz ist die Verwendung eines Web-Session-Cookies (_token nach dem Login in einem echten Browser). Dieses Projekt verwendet Camoufox, um ein persistentes Firefox-Profil zu erhalten, sodass das Cookie über Neustarts des MCP-Servers hinweg erhalten bleibt.

Related MCP server: cycles-mcp-server

Festes 5-Stunden-Fenster (kein rollierendes Fenster)

Laut offizieller MiniMax-Dokumentation:

Das Kontingent im Tarif wird durch ein festes 5-Stunden-Fenster und ein Wochenfenster gesteuert; nicht verbrauchtes Kontingent wird nicht in den nächsten Abrechnungszeitraum übertragen.

Die Fenstergrenzen sind also feste Uhrzeitfenster (typischerweise CST 00:00, 10:00, 15:00, 20:00 usw.), nicht rollierend ab deiner ersten Anfrage. Wenn du wenige Sekunden vor dem Fensterwechsel abfragst, erhältst du Daten des nächsten Fensters. Die Felder interval_start_iso / interval_end_iso in der Antwort zeigen dir, welches Fenster genau gemeint ist.

Einzeilige Installation

# 方式 1：从 PyPI 安装（推荐）
pip install minimax-remaining-mcp
# 或
uv pip install minimax-remaining-mcp
# 或
uvx minimax-remaining-mcp    # 不安装直接运行

# 方式 2：从 GitHub 安装（无需 PyPI 账号）
pip install git+https://github.com/yang-cc/minimax-remaining-mcp.git

# 方式 3：本地开发模式
git clone https://github.com/yang-cc/minimax-remaining-mcp.git
cd minimax-remaining-mcp
uv venv .venv --python 3.12
uv pip install -e .

Einmaliger Login

Da es keinen Bearer-Token-Pfad gibt, musst du dich zuerst einmal manuell in Camoufox anmelden:

# 1. 启动服务器
python -m minimax_remaining_mcp.server
# 2. 在 MCP 客户端里调用：
minimax_login(timeout_seconds=600)

Der Camoufox-Browser öffnet sich und zeigt die MiniMax-Loginseite. Bitte führe manuell die Cloudflare-/CAPTCHA-Verifizierung durch, melde dich mit deinem Konto an, bis der Browser die API-Keys-Seite erreicht. Der Server erkennt das _token-Cookie automatisch und speichert die Sitzung dauerhaft in data/cookies.json.

🔌 DeepSeek Harness (DSH) Integration

DSH lädt MCP-Server über @deepseek-ai/dsh-mcp-client. Füge den folgenden Abschnitt in ~/.dsh/profiles/web/cordis.patch.yml ein (beachte: der Paketname ist minimax-remaining-mcp, aber der Python-Modulpfad ist minimax_remaining_mcp.server):

- insert:
  - id: minimax-remaining-mcp
    name: '@deepseek-ai/dsh-mcp-client'
    config:
      serverName: minimax
      transport: stdio
      command: <repo>/.venv/Scripts/python.exe   # 或 uv 环境的 python
      args: ['-u', '-m', 'minimax_remaining_mcp.server']
      env:
        # 暂停阈值：5h 剩余低于 30% 时触发代理暂停
        MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT: '30'
        # 储存目录（可选，默认 ./data）
        # MINIMAX_DATA_DIR: E:\\codex_dir\\.dsh\\state\\minimax-remaining-mcp
      failOnStartupError: false
      toolCallTimeoutMs: 180000

DSH-Integrationshinweise

Typische Verwendung in DSH

Nach dem Start von DSH wird minimax_status() aufgerufen, um das verbleibende Kontingent zu prüfen. Du kannst den Agenten trainieren, vor jedem MiniMax-API-Aufruf einmal minimax_status() aufzurufen und das Feld should_pause zu beobachten:

remaining_percent_5h < 30  → should_pause=true → 代理应停下来或转做其他事
remaining_percent_5h >= 30 → should_pause=false → 可以继续调用

Eine gründlichere Lösung ist der Aufruf von minimax_wait_for_quota(), das blockiert, bis das Kontingent wieder über dem Schwellenwert liegt (Standard: MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT), sodass der Agent keine eigene Polling-Logik schreiben muss.

Werkzeugübersicht

⚠️ Erster Kaltstart (Camoufox) kann langsam sein

Beim ersten Start von Camoufox durch minimax_smoke() und minimax_login() muss das persistente Firefox-Profil entpackt, die sqlite-Datenbank initialisiert, Erweiterungen geladen usw. werden. Das dauert normalerweise 30-90 Sekunden (abhängig von der Festplattengeschwindigkeit). Das ist normales Verhalten beim Kaltstart von Camoufox, kein Bug – spätere Starts nutzen den Cache in data/profile/ und sind in Sekunden abgeschlossen.

Wenn der erste Aufruf das toolCallTimeoutMs deines MCP-Clients (DSH-Standard 180s) überschreitet und abgebrochen wird, wiederhole einfach den Aufruf, um das Ergebnis zu sehen. Wenn du häufige Kaltstarts erwartest (z. B. in CI), kannst du das toolCallTimeoutMs des entsprechenden MCP-Clients auf 300000 (5 Minuten) erhöhen.

Beispielantwort von minimax_status()

Tatsächliche Diagnoseausgabe (wenn das 5h-Fenster erschöpft ist und eine Pause ausgelöst werden sollte):

Unten ist die normalisierte JSON-Struktur:

{
  "ok": true,
  "source": "coding_plan",
  "remaining_percent_5h": 76,             // 5h 窗口剩余 %
  "used_percent_5h": 24,                 // 5h 窗口已用 %
  "seconds_until_reset_human": "4h21m35s",
  "interval_end_iso": "2026-08-25T12:00:00+00:00",
  "interval_status_text": "active",      // active | exhausted | inactive
  "remaining_percent_weekly": 100,
  "seconds_until_weekly_reset_human": "5d08h42m",
  "total_credits": 14000,                // 套餐累计（周维度）
  "used_credits": 3188,
  "remaining_credits": 10812,
  "user_name": "...",
  "group_id": "...",
  "should_pause": false,                 // 低于阈值时为 true
  "model_remains": [
    { "model_name": "general",  "interval_remaining_percent": 76, "interval_status": 1 },
    { "model_name": "video",    "interval_remaining_percent": 100, "interval_status": 3 }
  ]
}

Semantik des Pausenschwellenwerts

MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT=30 bedeutet: Pausiere, wenn der Restprozentsatz des 5h-Fensters < 30% ist (d.h. mehr als 70% verbraucht). Verglichen wird remaining_percent_5h, nicht das kumulierte remaining_credits des Tarifs – das sind zwei unabhängige Kennzahlen.

Persistente Dateien

Der gesamte Zustand wird als reines JSON in data/ gespeichert (durch .gitignore ausgeschlossen):

data/
├── cookies.json                # Camoufox 会话 cookie
├── session.json                # 最近一次登录元数据
├── window.json                 # 代理本地的 5h 观测窗口
├── last_usage.json             # 最近一次成功的 API 响应（缓存）
└── profile/                    # Camoufox 持久化 Firefox profile（~150 MB）

Wenn coding_plan/remains 401/403 zurückgibt, wird der vollständige Antwortkörper in data/last_coding_plan_failure.json geschrieben, um die Fehlersuche zu erleichtern – schau zuerst in diese Datei, bevor du vermutest, dass der Dienst ausgefallen ist.

Umgebungsvariablen

Alle optional, Standardwerte siehe Tabelle unten.

Lokale Entwicklung & Debugging

# 启动 MCP 服务器（stdio 模式）
.venv\Scripts\python.exe -u -m minimax_remaining_mcp.server
# 或（Windows）
run.bat

# 直接探测 coding_plan 接口（无需 MCP / 浏览器）
.venv\Scripts\python.exe probe_coding_plan.py

# 检查持久化状态
cat data/cookies.json | head -c 200
cat data/session.json
cat data/last_coding_plan_failure.json   # 如果存在

Veröffentlichung als PyPI-Paket (für Wartende)

# 安装打包工具
pip install build twine

# 在项目根目录构建 wheel + sdist
python -m build
# → dist/minimax_remaining_mcp-0.1.0-py3-none-any.whl
# → dist/minimax_remaining_mcp-0.1.0.tar.gz

# 检查产物
twine check dist/*

# 上传到 PyPI（需要先 `twine login` 或用 token）
twine upload dist/*
# 或：uv publish dist/*

Nach der Veröffentlichung kann jeder:

pip install minimax-remaining-mcp
uv pip install minimax-remaining-mcp
uvx minimax-remaining-mcp    # 临时运行

Einschränkungen

• Kein Bearer-Key-Pfad. MiniMax stellt derzeit keine Abonnement-Schlüssel für die Coding-Plan-API aus; die Verwendung des api_key der Webkonsole als Bearer führt zu 2062 "no active token plan". Der einzige funktionierende Weg ist das Session-Cookie.

• Cloudflare / CAPTCHA muss manuell abgeschlossen werden. Der erste Login muss von einer echten Person durchgeführt werden. Dieses Projekt nutzt keine Captcha-Lösungsdienste.

• Das 5h-Fenster ist ein festes CST-Zeitfenster. Wenn du vor dem Fensterwechsel abfragst, erhältst du Daten des nächsten Fensters. interval_start_iso / interval_end_iso zeigen dir, welches Fenster genau gemeint ist.

• Das Tarifkumulierung (remaining_credits) wird nicht übertragen. Es ist ein wöchentlicher kumulierter Pool, der nicht mit dem 5h-Fenster-Reset auf null gesetzt wird.

Lizenz

MIT – siehe LICENSE.