minimax-remaining-mcp

Servidor MCP: permite que los agentes de IA sepan cuánto crédito queda en el plan MiniMax Token Plan, y cuándo deben pausarse para evitar activar la limitación de frecuencia.

Compatible con DeepSeek Harness (DSH), Claude Desktop, Cursor y todos los demás clientes compatibles con el protocolo MCP.

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

Antecedentes del proyecto

El panel "límite de 5 h / 61 % usado / se restablece en 2 h 56 m" de la consola web de MiniMax está impulsado en realidad por dos interfaces HTTP:

1. /v1/api/openplatform/coding_plan/remains?GroupId=… — porcentaje restante + cuenta regresiva de la ventana fija de 5 horas

2. /backend/account/token_plan_credit — crédito acumulado del pool del plan (dimensión semanal)

Ninguna de las dos interfaces acepta la api_key de la interfaz web (que tiene el formato sk-cp-...) como Bearer Token: si se usa, devuelve base_resp = {2062, "no active token plan"}. La única opción viable es usar la cookie de sesión web (el _token tras iniciar sesión en un navegador real). Este proyecto utiliza Camoufox para mantener un perfil de Firefox persistente, de modo que la cookie se conserve entre reinicios del servidor MCP.

Related MCP server: cycles-mcp-server

Ventana fija de 5 horas (no deslizante)

Según la documentación oficial de MiniMax:

El crédito del plan está controlado por una ventana fija de 5 horas y una ventana semanal; el crédito del plan no utilizado no se transfiere al siguiente ciclo de facturación.

Por lo tanto, los límites de la ventana son franjas horarias de reloj fijas (típicamente CST 00:00, 10:00, 15:00, 20:00, etc.), no una ventana deslizante que comienza con tu primera solicitud. Si consultas unos segundos antes del cambio de ventana, obtendrás los datos de la ventana siguiente. Los campos interval_start_iso / interval_end_iso de la respuesta te indican exactamente de qué período se trata.

Instalación en una línea

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

Inicio de sesión único

Como no existe la vía de Bearer Token, primero debes iniciar sesión manualmente una vez en Camoufox:

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

El navegador Camoufox se abrirá mostrando la página de inicio de sesión de MiniMax. Completa manualmente la verificación de Cloudflare / CAPTCHA e inicia sesión hasta que el navegador llegue a la página de API Keys. El servidor detectará automáticamente la cookie _token y guardará la sesión de forma persistente en data/cookies.json.

🔌 Integración con DeepSeek Harness (DSH)

DSH carga el servidor MCP a través de @deepseek-ai/dsh-mcp-client. Agrega el siguiente bloque en ~/.dsh/profiles/web/cordis.patch.yml (ten en cuenta que el nombre del paquete es minimax-remaining-mcp, pero la ruta del módulo Python es 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

Puntos clave de la integración con DSH

Uso típico en DSH

Al iniciarse, DSH llama a minimax_status() para determinar el crédito restante. Puedes entrenar al agente para que llame a minimax_status() una vez antes de cada llamada a la API de MiniMax y observe el campo should_pause:

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

Una solución más completa es llamar a minimax_wait_for_quota(), que se bloquea hasta que el crédito vuelva a estar por encima del umbral (por defecto, MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT), ahorrándole al agente tener que escribir su propia lógica de sondeo.

Resumen de herramientas

⚠️ El primer arranque en frío (Camoufox) puede ser lento

La primera vez que minimax_smoke() y minimax_login() inician Camoufox, es necesario descomprimir el perfil de Firefox persistente, inicializar la base de datos sqlite, cargar las extensiones, etc. Normalmente tarda 30-90 segundos (según la velocidad del disco). Esto es un comportamiento normal del arranque en frío de Camoufox, no un error; los arranques posteriores reutilizan la caché en data/profile/ y se completan en cuestión de segundos.

Si la primera llamada se cancela por superar el toolCallTimeoutMs de tu cliente MCP (180 s por defecto en DSH), reinténtala una vez y verás el resultado. Si prevés arranques en frío frecuentes (por ejemplo, en CI), puedes ajustar el toolCallTimeoutMs del cliente MCP correspondiente a 300000 (5 minutos).

Ejemplo de respuesta de minimax_status()

Salida de diagnóstico real (cuando la ventana de 5 h está agotada y debe activarse la pausa):

A continuación se muestra la estructura JSON normalizada:

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

Semántica del umbral de pausa

MINIMAX_PAUSE_THRESHOLD_REMAINING_PCT=30 significa pausar cuando el porcentaje restante de la ventana de 5 h sea < 30% (es decir, cuando se haya consumido más del 70%). Se compara con remaining_percent_5h, no con el remaining_credits acumulado del plan: son dos métricas independientes.

Archivos persistentes

Todo el estado se almacena como JSON puro en data/ (excluido por .gitignore):

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

Si coding_plan/remains devuelve 401/403, el cuerpo completo de la respuesta se escribirá en data/last_coding_plan_failure.json para facilitar el diagnóstico: antes de sospechar que el servicio se ha caído, revisa este archivo.

Variables de entorno

Todas son opcionales; los valores predeterminados se indican en la siguiente tabla.

Desarrollo y depuración locales

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

Publicar el paquete en PyPI (para mantenedores)

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

Después de la publicación, cualquiera puede:

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

Limitaciones

• No existe la vía de Bearer-key. MiniMax actualmente no emite claves de suscripción para la API de Coding Plan; usar la api_key de la consola web como Bearer devuelve 2062 "no active token plan". Lo único viable es la cookie de sesión.

• Cloudflare / CAPTCHA deben completarse manualmente. El primer inicio de sesión debe realizarlo una persona real. Este proyecto no se integra con ningún servicio de resolución de CAPTCHA.

• La ventana de 5 h es una franja horaria fija de CST. Si consultas antes del cambio de ventana, obtendrás los datos de la siguiente ventana. interval_start_iso / interval_end_iso te indican exactamente qué período es.

• El acumulado del plan (remaining_credits) no se transfiere. Es un pool acumulado de dimensión semanal y no se pone a cero con el restablecimiento de la ventana de 5 h.

Licencia

MIT — consulta LICENSE.