Skip to main content
Glama

minimax-remaining-mcp

MCP server: lets AI agents know how much quota is left in the MiniMax Token Plan, and when they should pause themselves to avoid hitting rate limits.

Works with DeepSeek Harness (DSH), Claude Desktop, Cursor, and any other client compatible with the MCP protocol.

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

Project Background

The MiniMax web console's "5h cap / 61% used / resets in 2h56m" panel is actually driven by two HTTP endpoints:

  1. /v1/api/openplatform/coding_plan/remains?GroupId=… — remaining percentage + countdown for the 5-hour fixed window

  2. /backend/account/token_plan_credit — cumulative credit of the plan pool (weekly)

Neither endpoint accepts the api_key shown on the web UI (which looks like sk-cp-...) as a Bearer Token — using it returns base_resp = {2062, \"no active token plan\"}. The only viable approach is to use the web session cookie (_token after logging in through a real browser). This project uses Camoufox to maintain a persistent Firefox profile, so cookies survive MCP server restarts.

Related MCP server: llm-quota-mcp

5-Hour Fixed Window (Not a Sliding Window)

In-plan quota is controlled by a 5-hour fixed window and a weekly window; unused in-plan quota is not carried over to the next billing cycle.

So the window boundaries are fixed clock periods (typically CST 00:00, 10:00 / 15:00 / 20:00, etc.), rather than rolling from your first request. If you query a few seconds before a window switch, the response returns the next window's data. The interval_start_iso / interval_end_iso fields in the response tell you exactly which period it is.

One-Line 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 .

One-Time Login

Since there is no Bearer Token path, you need to log in manually once in Camoufox:

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

The Camoufox browser will pop up and open the MiniMax login page. Please complete the Cloudflare / CAPTCHA verification and log in manually until the browser reaches the API Keys page. The server automatically detects the _token cookie and persists the session to data/cookies.json.

🔌 DeepSeek Harness (DSH) Integration

DSH loads MCP servers through @deepseek-ai/dsh-mcp-client. Append the following to ~/.dsh/profiles/web/cordis.patch.yml (note the package name is minimax-remaining-mcp, but the Python module path is 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 Integration Notes

Note

Description

-u flag

Makes Python stdio unbuffered so the DSH console can see MCP server logs immediately.

Python interpreter path

Depends on the installation method:• pip install → use the system Python or the python in your venv• uv pip install -e . → <repo>/.venv/Scripts/python.exe• uv tool install → uv tool run minimax-remaining-mcp also works, but stdio buffering requires -u

Login required on first start

If data/cookies.json does not exist when DSH starts the MCP server, calling minimax_login() will pop up a browser window.

Restart DSH

After modifying cordis.patch.yml, you must restart DSH for the changes to take effect.

failOnStartupError: false

Recommended to set to false, so DSH does not error out immediately even if cookies are not ready on first startup.

Isolated persistence directories

When multiple projects share the same DSH, it is recommended to use a different MINIMAX_DATA_DIR for each project to avoid cookies overwriting each other.

Typical Usage in DSH

After DSH starts, it calls minimax_status() to determine the remaining quota. You can train the agent to call minimax_status() once before each MiniMax API call and observe the should_pause field:

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

A more thorough approach is to call minimax_wait_for_quota(), which blocks until the quota is back above the threshold (default MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT), saving the agent from writing its own polling logic.

Tool Overview

Tool

Purpose

minimax_status()

All the numbers from the web panel: 5h remaining/used %, countdown, plan accumulation. Sets should_pause=true when below the threshold.

minimax_window()

Returns only the agent-local 5h observation window state (separate from MiniMax's fixed window, used only for agent self-throttling).

minimax_consume(delta=N)

Adds N to the local window consumption counter. Call once after each MiniMax API call.

minimax_wait_for_quota(target_pct=None, poll_seconds=60)

Blocks until the 5h remaining percentage is ≥ target_pct. Can be interrupted by closing the MCP connection.

minimax_login(timeout_seconds=600)

Pops up a Camoufox browser window for manual login.

minimax_smoke()

Quick Camoufox health check (opens example.com).

minimax_info()

Static configuration + metadata from the most recent session.

minimax_clear(confirm=True)

Clears cookies / session / window state.

⚠️ First Cold Start (Camoufox) Is Slow

The first time minimax_smoke() and minimax_login() start Camoufox, they need to unpack the persisted Firefox profile, initialize the sqlite database, load extensions, and so on, which usually takes 30-90 seconds (depending on disk speed). This is normal Camoufox cold-start behavior, not a bug — subsequent starts reuse the cache in data/profile/ and finish in seconds.

If the first call exceeds your MCP client's toolCallTimeoutMs (DSH default 180s) and is aborted, just retry once and you'll see the result. If you expect frequent cold starts (for example, running in CI), you can set the toolCallTimeoutMs of the corresponding MCP client to 300000 (5 minutes).

minimax_status() Response Example

Actual diagnostic output (when the 5h window is exhausted and a pause should be triggered):

minimax_status example output

Below is the normalized JSON structure:

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

Pause Threshold Semantics

MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT=30 means pause when the 5h window's remaining percentage is < 30% (i.e., more than 70% used). It compares remaining_percent_5h, not the plan-accumulated remaining_credits — these are independent metrics.

Persistent Files

All state is stored as plain JSON in data/ (excluded via .gitignore):

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

If coding_plan/remains returns 401/403, the full response body is written to data/last_coding_plan_failure.json for troubleshooting — check this file before suspecting the service is down.

Environment Variables

All are optional; default values are shown in the table below.

Variable

Default

Description

MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT

30

Pause when the 5h remaining falls below this.

MINIMAX_WINDOW_SECONDS

18000

Agent-local window length (5h).

MINIMAX_HEADFUL_ON_LOGIN

1

Forces the browser window to show during login.

MINIMAX_CAMOUFOX_OS

auto

windows / macos / linux.

MINIMAX_CAMOUFOX_LOCALE

zh-CN

Browser language.

MINIMAX_HTTP_TIMEOUT

15

API request timeout (seconds).

MINIMAX_DATA_DIR

./data

cookies / session storage directory.

MINIMAX_WEB_URL

https://platform.minimaxi.com

Overrides the console base URL.

MINIMAX_USAGE_API_URL

…/backend/account/token_plan_credit

Plan pool endpoint.

MINIMAX_REMAINS_API_URL

…/1/api/openplatform/coding_plan/remains

5h window endpoint.

MINIMAX_REMAINS_API_URL_FALLBACK

api.minimaxi.com/...

Used when the primary endpoint fails.

MINIMAX_LOGIN_HINT_URL

…/use-center/basic-information/interface-key

Login landing page.

Local Development & 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   # 如果存在

Packaging & Publishing to PyPI (for Maintainers)

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

After publishing, anyone can:

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

Limitations

  • No Bearer-key path. MiniMax does not currently issue a subscription key for the Coding Plan API; using the web console's api_key as a Bearer returns 2062 \"no active token plan\". The only viable option is the session cookie.

  • Cloudflare / CAPTCHA must be completed manually. The initial login must be completed by a real person. This project does not integrate with any captcha-solving service.

  • The 5h window is a fixed CST period. Querying before a window switch returns the next window's data. interval_start_iso / interval_end_iso tell you exactly which period.

  • Plan accumulation (remaining_credits) is not carried over. It is a weekly cumulative pool and is not reset when the 5h window resets.

License

MIT — see LICENSE for details.

Available Tools

8 tools
minimax_clearA

Wipe persisted cookies, session metadata, and window state.

Requires confirm=True to actually delete (otherwise returns a preview of what would be removed).

Inputs: confirm. Returns: object

minimax_consumeA

Increment the local 5h-window consumption counter by delta.

Call this once per MiniMax API call (or batch) your agent makes. Combined with minimax_status() it lets the agent pace itself without waiting for MiniMax's 5h rate limit to bite.

Inputs: delta. Returns: object

minimax_infoB

Return static configuration + last-known session metadata.

Inputs: no named parameters. Returns: object

minimax_loginA

Launch a headful Camoufox browser so the user can log in manually.

Returns once the _token cookie appears in the browser. The server detects login success automatically; no further action needed.

Inputs: timeout_seconds. Returns: object

minimax_smokeA

Quick health check: launch headless Camoufox and load example.com.

Inputs: no named parameters. Returns: object

minimax_statusA

Return current Token Plan status (the same numbers shown on the page).

Reads the 5h fixed-window remaining/used percent, time until reset, and weekly window. Use this before any substantial work that will call MiniMax models. If should_pause is true, the agent should sleep until the 5h window resets (see minimax_wait_for_quota).

The web console actually fires two distinct requests; we mirror both so the response matches what the user sees on screen:

  1. /v1/api/openplatform/coding_plan/remains?GroupId={gid} powers the "5h 限额 / X% 已用 / 2h56m 后重置" panel.

  2. /backend/account/token_plan_credit powers the "套餐用量" panel (total / used / remaining credits).

Auth for both uses the persisted web-session cookies (Camoufox capture). When cookies are missing or stale, the failure body is saved to <data_dir>/last_coding_plan_failure.json so the cause can be diagnosed.

Inputs: no named parameters. Returns: object

minimax_wait_for_quotaA

Block until the 5h window remaining percent exceeds target_remaining_percent.

Polls minimax_status() every poll_seconds and exits when the threshold is satisfied (default = pause_threshold_remaining_pct). Cancellable by closing the MCP connection. Intended for use by an agent that wants to truly pause (not just sleep a fixed amount).

Inputs: poll_seconds, target_remaining_percent. Returns: object

minimax_windowA

Return only the agent-local 5h observation window (no API call).

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation4/5

    Tools are mostly distinct: minimax_status queries live MiniMax quota, minimax_window returns local tracking state, and consume/wait/login/clear/info each target a single operation. The only realistic confusion is minimax_window vs minimax_status, since both concern the 5h window, but the descriptions explicitly separate local no-API state from server-reported state.

    Naming Consistency4/5

    All tools share the minimax_ prefix and split sensibly into noun-style read tools (window, status, info) and verb-style actions (login, consume, clear, wait_for_quota, smoke). It is not a uniform verb_noun pattern, but the convention is predictable and easy to parse.

    Tool Count5/5

    Eight tools is a well-scoped size for a quota-management server. Each tool earns its place: authentication, live status, local consumption tracking, blocking wait, state reset, health check, and configuration/session info.

    Completeness5/5

    The toolset covers the full lifecycle: authenticate, check live quota, track local usage, pause until reset, inspect config, and wipe state. There are no obvious missing operations for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables agents to check remaining Anthropic and OpenAI rate-limit quotas with reset times, plus Hermes Agent token usage, so bots can throttle or stop before hitting limits.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets a coding agent inspect its own account's subscription limit windows, usage, and cost history, and decide whether to pause and sleep until a limit resets rather than failing mid-task. Supports multiple accounts and providers such as Claude Code and Codex.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Lets an AI agent check its own Claude and Codex usage limits — used percentages and exact reset times for session and weekly windows — so it can plan long-running work around resets instead of dying mid-task. It reads local, credential-free sources by default, always reports which source answered, and ships a hook that pushes quota state into context automatically.
      1
      MIT