minimax-remaining-mcp

MCP-сервер: сообщает AI-агенту, сколько квоты осталось в тарифном плане MiniMax Token Plan, и когда стоит поставить себя на паузу, чтобы не упереться в лимиты.

Совместим с DeepSeek Harness (DSH), Claude Desktop, Cursor и любыми другими клиентами, поддерживающими протокол MCP.

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

Предыстория проекта

Панель «5h лимит / 61% использовано / сброс через 2h56m» в веб-консоли MiniMax на самом деле обслуживается двумя HTTP-эндпоинтами:

1. /v1/api/openplatform/coding_plan/remains?GroupId=… — процент оставшейся квоты в фиксированном 5-часовом окне + обратный отсчёт

2. /backend/account/token_plan_credit — накопленная квота пула тарифного плана (недельное измерение)

Оба эндпоинта не принимают api_key из веб-интерфейса (выглядит как sk-cp-...) в качестве Bearer Token — с ним возвращается base_resp = {2062, "no active token plan"}. Единственный рабочий способ — использовать cookie веб-сессии (_token после входа в настоящем браузере). Этот проект использует Camoufox для поддержания постоянного Firefox-профиля, чтобы cookie сохранялись между перезапусками MCP-сервера.

Related MCP server: cycles-mcp-server

Фиксированное 5-часовое окно (не скользящее)

Согласно официальной документации MiniMax:

Квота в рамках тарифного плана контролируется фиксированным 5-часовым окном и недельным окном; неиспользованная квота тарифного плана не переносится на следующий расчётный период.

Таким образом, границы окна — это фиксированные отрезки времени (обычно CST 00:00 10:00 / 15:00 / 20:00 и т.д.), а не скользящее окно от вашего первого запроса. Если вы выполните запрос за несколько секунд до переключения окна, в ответе будут данные следующего окна. Поля interval_start_iso / interval_end_iso в ответе подскажут, о каком именно отрезке идёт речь.

Установка одной строкой

# 方式 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 .

Разовый вход

Поскольку пути с Bearer Token нет, нужно один раз вручную войти в Camoufox:

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

Откроется браузер Camoufox со страницей входа MiniMax. Пожалуйста, вручную пройдите проверку Cloudflare / CAPTCHA, войдите в аккаунт, пока браузер не откроет страницу API Keys. Сервер автоматически обнаружит cookie _token и сохранит сессию в data/cookies.json.

🔌 Интеграция с DeepSeek Harness (DSH)

DSH загружает MCP-серверы через @deepseek-ai/dsh-mcp-client. Добавьте следующий фрагмент в ~/.dsh/profiles/web/cordis.patch.yml (обратите внимание: имя пакета — minimax-remaining-mcp, но путь к Python-модулю — 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

Типичное использование в DSH

После запуска DSH вызывает minimax_status() для определения остатка квоты. Вы можете обучить агента вызывать minimax_status() перед каждым обращением к MiniMax API и проверять поле should_pause:

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

Более радикальный вариант — вызвать minimax_wait_for_quota(): он блокирует выполнение, пока квота не восстановится выше порога (по умолчанию MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT), избавляя агента от необходимости писать собственную логику опроса.

Обзор инструментов

⚠️ Первый холодный запуск (Camoufox) может быть медленным

При первом запуске Camoufox через minimax_smoke() и minimax_login() требуется распаковать постоянный Firefox-профиль, инициализировать базу данных sqlite, загрузить расширения и т.д. Обычно это занимает 30-90 секунд (зависит от скорости диска). Это нормальное поведение холодного запуска Camoufox, а не баг — последующие запуски используют кэш из data/profile/ и выполняются за секунды.

Если первый вызов превысил toolCallTimeoutMs вашего MCP-клиента (в DSH по умолчанию 180 с) и был прерван, повторите попытку — результат появится. Если вы ожидаете частые холодные запуски (например, в CI), увеличьте toolCallTimeoutMs соответствующего MCP-клиента до 300000 (5 минут).

Пример ответа minimax_status()

Фактический диагностический вывод (когда 5-часовое окно исчерпано и следует активировать паузу):

Ниже приведена нормализованная структура JSON:

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

Семантика порога паузы

MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT=30 означает паузу, когда остаток процента в 5-часовом окне < 30% (т.е. использовано более 70%). Сравнивается с remaining_percent_5h, а не с накопленным remaining_credits тарифного плана — это два независимых показателя.

Файлы персистентности

Все состояния хранятся в виде чистого JSON в data/ (исключено через .gitignore):

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

Если coding_plan/remains возвращает 401/403, полное тело ответа записывается в data/last_coding_plan_failure.json для удобной диагностики — прежде чем подозревать, что сервис не работает, посмотрите этот файл.

Переменные окружения

Все необязательны, значения по умолчанию см. в таблице.

Локальная разработка и отладка

# 启动 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   # 如果存在

Публикация пакета на PyPI (для сопровождающих)

# 安装打包工具
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/*

После публикации любой желающий может:

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

Ограничения

• Пути с Bearer-key нет. MiniMax в настоящее время не выдаёт подписочные ключи для Coding Plan API; использование api_key из веб-консоли в качестве Bearer возвращает 2062 "no active token plan". Единственный рабочий вариант — cookie сессии.

• Cloudflare / CAPTCHA нужно проходить вручную. Первый вход должен выполнить человек. Этот проект не подключает никакие сервисы распознавания капчи.

• 5-часовое окно — фиксированные отрезки по CST. При запросе перед переключением окна вы получите данные следующего окна. interval_start_iso / interval_end_iso подскажут, о каком именно отрезке речь.

• Накопление по тарифу (remaining_credits) не переносится. Это накопительный пул недельного измерения, он не обнуляется при сбросе 5-часового окна.

Лицензия

MIT — подробности в LICENSE.