Manus MCP

Un servidor MCP que proporciona a Claude Code control programático total sobre Manus.im a través de la API oficial de Manus v2. Implementa los 30 endpoints documentados, 3 herramientas compuestas para flujos de trabajo comunes y un receptor de webhooks local con verificación de firma RSA-SHA256.

• Estado: listo para producción (usuario único) — v0.1.1

• Lenguaje: Python 3.11+

• Transporte: stdio (nativo de Claude Code)

• URL base: https://api.manus.ai

Cobertura verificada (v0.1.1)

Consulta docs/SECURITY.md y docs/RELEASE.md para conocer el flujo de producción.

Qué incluye

30 envoltorios de API directos

3 herramientas compuestas

• manus_file_upload — crea una URL prefirmada, sube los bytes y espera a status=uploaded. Acepta path, base64 o una url pública.

• manus_task_wait — sondea una tarea hasta que alcanza un estado terminal (stopped / waiting / error) y devuelve nuevos mensajes además de detalles de espera (event_id + esquema de respuesta).

• manus_website_publish_and_wait — publica un sitio y espera hasta que esté published o failed.

3 herramientas de webhook (leídas desde la base de datos SQLite local)

• manus_webhook_events_list — lista los eventos recibidos con filtros.

• manus_webhook_events_get — obtiene un evento por event_id.

• manus_webhook_events_clear — elimina los eventos recibidos.

Total: 36 herramientas MCP.

Instalación

cd path/to/Manus-MCP
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
# source .venv/bin/activate

pip install -e ".[dev]"

Configuración de la clave de API

Coloca un archivo .env en la raíz del proyecto (se proporciona una plantilla .env.example). Se aceptan ambos nombres de variable:

MANUS_API_KEY=sk-...
# or, for backwards compatibility:
# ManusAPI=sk-...

Prioridad: process.env > .env.

Configuraciones opcionales:

MANUS_BASE_URL=https://api.manus.ai
MANUS_HTTP_TIMEOUT=60
MANUS_LOG_LEVEL=INFO

Registro en Claude Code

Añade lo siguiente a .claude/settings.json (a nivel de proyecto) o ~/.claude/settings.json (global):

{
  "mcpServers": {
    "manus": {
      "command": "python",
      "args": ["-m", "manus_mcp"],
      "cwd": "path/to/Manus-MCP"
    }
  }
}

Si MANUS_API_KEY no está configurada globalmente, pásala explícitamente:

{
  "mcpServers": {
    "manus": {
      "command": "python",
      "args": ["-m", "manus_mcp"],
      "cwd": "path/to/Manus-MCP",
      "env": { "MANUS_API_KEY": "sk-..." }
    }
  }
}

Reinicia Claude Code: las herramientas manus_* aparecerán en la lista de herramientas.

Verificación

Sin iniciar el servidor:

python scripts/list_tools.py

Contra la API real:

python scripts/smoke.py

Pruebas unitarias:

pytest

Lint y tipos:

ruff check .
mypy manus_mcp

Ejemplos de uso desde Claude Code

manus_task_create { "message": { "content": "Give me a 5-bullet summary of today's AI news" } }

La respuesta contiene un task_id. Luego:

manus_task_wait { "task_id": "<id>", "timeout_sec": 600 }

Cuando termina, obtienes last_assistant_message con la respuesta final y new_messages con el historial de la conversación.

Subir un archivo y adjuntarlo a una tarea:

manus_file_upload { "source": { "path": "C:/docs/report.pdf" } }
manus_task_create {
  "message": {
    "content": [
      { "type": "text", "text": "Summarize this report" },
      { "type": "file", "file_id": "<file_id>" }
    ]
  }
}

Receptor de webhooks (opcional)

Un receptor local para eventos task_created / task_stopped con verificación completa de firma RSA-SHA256 según ManusAPIDocs/webhooks/security.md.

1. Configurar variables de entorno

MANUS_WEBHOOK_PUBLIC_URL=https://your-tunnel.example.com/manus/webhook
MANUS_WEBHOOK_HOST=127.0.0.1
MANUS_WEBHOOK_PORT=8787
# MANUS_WEBHOOK_DB_PATH=...  # defaults to %LOCALAPPDATA%\manus-mcp\events.db on Windows

MANUS_WEBHOOK_PUBLIC_URL debe coincidir exactamente con la URL a la que llama Manus. La carga útil de firma de Manus incluye esta URL, por lo que incluso un error tipográfico hará que cada evento sea rechazado.

2. Iniciar un túnel

Por ejemplo, con Cloudflare Tunnel:

cloudflared tunnel --url http://localhost:8787

o ngrok:

ngrok http 8787

3. Ejecutar el receptor

python -m manus_mcp.webhook_receiver
# or: manus-mcp-webhook --host 127.0.0.1 --port 8787

4. Registrar el webhook con Manus

En Claude Code:

manus_webhook_create { "url": "https://your-tunnel.example.com/manus/webhook" }

5. Leer eventos

manus_webhook_events_list { "event_type": "task_stopped", "limit": 20 }
manus_webhook_events_get { "event_id": "..." }
manus_webhook_events_clear { "before_received_at": 1704000000 }

Arquitectura

manus_mcp/
├── __main__.py          # stdio entrypoint
├── server.py            # MCP Server bootstrap
├── config.py            # pydantic-settings
├── logger.py            # stderr-only logger
├── client/
│   ├── manus_client.py  # async httpx client + retry
│   ├── rate_limiter.py  # per-endpoint token bucket (from rate-limits.md)
│   ├── retry.py         # exponential backoff + jitter
│   └── errors.py        # ManusApiError / ManusNetworkError
├── schemas/             # pydantic models for each resource (tasks, projects, ...)
├── tools/               # @manus_tool registration for all 36 tools
│   ├── tasks.py projects.py skills.py agents.py
│   ├── files.py webhooks.py usage.py connectors.py
│   ├── browser.py website.py
│   └── composite.py     # task_wait / file_upload / website_publish_and_wait
└── webhook_receiver/
    ├── signature.py     # RSA-SHA256 verification using {ts}.{url}.{sha256_hex(body)}
    ├── storage.py       # SQLite WAL
    ├── server.py        # Starlette + uvicorn
    ├── tools.py         # events_list / events_get / events_clear
    └── __main__.py

Límites de tasa

El cliente respeta los límites de la API (ventana deslizante de 60 segundos) y reintenta de forma transparente las respuestas 429 con retroceso + jitter. Los límites provienen de ManusAPIDocs/getting-started/rate-limits.md:

• 10/min: task.create, task.sendMessage

• 40/min: todas las mutaciones

• 100/min: todas las llamadas de solo lectura

• 600/min: usage.*

Seguridad

• La clave de API nunca se registra.

• El receptor de webhooks verifica las firmas y rechaza las marcas de tiempo con más de 5 minutos de antigüedad.

• La clave pública se almacena en caché durante 1 hora.

• SQLite se abre en modo WAL con check_same_thread=False para un acceso seguro de múltiples lectores.

Licencia

MIT.