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
                                 └─────────────┘

项目背景

MiniMax 网页控制台的 "5h 限额 / 61% 已用 / 2h56m 后重置" 面板其实由 两个 HTTP 接口驱动：

1. /v1/api/openplatform/coding_plan/remains?GroupId=… — 5 小时固定窗口的 剩余百分比 + 倒计时
2. /backend/account/token_plan_credit — 套餐池（周维度）的累计额度

两个接口都不接受网页 UI 上的 api_key（长得像 sk-cp-...）作为 Bearer Token —— 用它会返回 base_resp = {2062, "no active token plan"}。 唯一可行的方案是使用网页会话 cookie（真实浏览器登录后的 _token）。 本项目用 Camoufox 维持一个持久化的 Firefox profile，让 cookie 在 MCP 服务器重启之间保留下来。

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 页面。 服务器会自动检测到 _token cookie 并把会话持久化到 data/cookies.json。

🔌 DeepSeek Harness (DSH) 集成

DSH 通过 @deepseek-ai/dsh-mcp-client 加载 MCP 服务器。在 ~/.dsh/profiles/web/cordis.patch.yml 里追加下面这段（注意 package 名是 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 集成要点

注意点	说明
-u 参数	让 Python stdio 不带缓冲，DSH 控制台能立刻看到 MCP 服务器日志。
Python 解释器路径	取决于安装方式： • pip install → 用系统 Python 或 venv 中的 python • uv pip install -e . → <repo>/.venv/Scripts/python.exe • uv tool install → uv tool run minimax-remaining-mcp 也行，但 stdio 缓冲需要 -u
首次启动需要登录	DSH 启动 MCP 服务器时如果 data/cookies.json 不存在，调用 minimax_login() 会弹出浏览器窗口。
重启 DSH	修改 cordis.patch.yml 后必须重启 DSH 才会生效。
failOnStartupError: false	推荐设为 false，这样即使首次启动时 cookie 还没准备好，DSH 也不会立即报错。
持久化目录隔离	多个项目共用同一个 DSH 时，建议每个项目用不同的 MINIMAX_DATA_DIR，避免 cookie 互相覆盖。

DSH 中的典型用法

DSH 启动后，会调用 minimax_status() 来判断剩余额度。你可以训练代理在 每次 MiniMax API 调用前先调用一次 minimax_status()，观察 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），省去代理自己 写轮询逻辑。

工具一览

工具	用途
minimax_status()	网页面板的全部数字：5h 剩余/已用 %、倒计时、套餐累计。低于阈值时设置 should_pause=true。
minimax_window()	仅返回代理本地的 5h 观测窗口状态（与 MiniMax 的固定窗口是分开的，仅用于代理自节流）。
minimax_consume(delta=N)	把本地窗口消费计数器加 N。每次 MiniMax API 调用后调用一次。
minimax_wait_for_quota(target_pct=None, poll_seconds=60)	阻塞到 5h 剩余百分比 ≥ target_pct。关闭 MCP 连接可中断。
minimax_login(timeout_seconds=600)	弹出 Camoufox 浏览器窗口用于手动登录。
minimax_smoke()	快速 Camoufox 健康检查（打开 example.com）。
minimax_info()	静态配置 + 最近一次会话元数据。
minimax_clear(confirm=True)	清空 cookies / session / window 状态。

⚠️ 首次冷启动（Camoufox）会比较慢

minimax_smoke() 和 minimax_login() 第一次启动 Camoufox 时，需要解压 持久化的 Firefox profile、初始化 sqlite 数据库、加载扩展等，通常需要 30-90 秒（视磁盘速度而定）。这是 Camoufox 冷启动的正常表现，不是 bug——后续启动会复用 data/profile/ 里的缓存，秒级完成。

如果首次调用超过了你的 MCP 客户端 toolCallTimeoutMs（DSH 默认 180s） 而被中止，重试一次即可看到结果。如果你预计会频繁冷启动（例如在 CI 里跑），可以把对应 MCP 客户端的 toolCallTimeoutMs 调到 300000（5 分钟）。

minimax_status() 响应示例

实际诊断输出(当 5h 窗口已耗尽、应触发暂停时):

下面是规范化后的 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 的意思是 当 5h 窗口的剩余 百分比 < 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 方便排查 —— 在怀疑服务挂了之前先 看这个文件。

环境变量

全部可选，默认值见下表。

变量	默认	说明
MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT	30	5h 剩余低于此值时暂停。
MINIMAX_WINDOW_SECONDS	18000	代理本地窗口长度（5h）。
MINIMAX_HEADFUL_ON_LOGIN	1	登录时强制显示浏览器窗口。
MINIMAX_CAMOUFOX_OS	auto	windows / macos / linux。
MINIMAX_CAMOUFOX_LOCALE	zh-CN	浏览器语言。
MINIMAX_HTTP_TIMEOUT	15	API 请求超时（秒）。
MINIMAX_DATA_DIR	./data	cookies / session 储存目录。
MINIMAX_WEB_URL	https://platform.minimaxi.com	覆盖控制台基础 URL。
MINIMAX_USAGE_API_URL	…/backend/account/token_plan_credit	套餐池 endpoint。
MINIMAX_REMAINS_API_URL	…/v1/api/openplatform/coding_plan/remains	5h 窗口 endpoint。
MINIMAX_REMAINS_API_URL_FALLBACK	api.minimaxi.com/...	主 endpoint 失败时使用。
MINIMAX_LOGIN_HINT_URL	…/user-center/basic-information/interface-key	登录落地页。

本地开发 & 调试

# 启动 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 需手动完成。 首次登录必须由真人完成。 本项目不接入任何打码服务。
• 5h 窗口是 CST 固定时段。 在窗口切换前查询，会拿到下一个窗口的数据。 interval_start_iso / interval_end_iso 告诉你具体是哪一段。
• 套餐累计（remaining_credits）不会结转。 它是周维度的累计池， 不会随 5h 窗口重置而清零。

许可证

MIT — 详见 LICENSE。