Manus MCP

Ein MCP-Server, der Claude Code die volle programmatische Kontrolle über Manus.im über die offizielle Manus API v2 gibt. Implementiert alle 30 dokumentierten Endpunkte, 3 zusammengesetzte Tools für gängige Arbeitsabläufe und einen lokalen Webhook-Empfänger mit RSA-SHA256-Signaturprüfung.

• Status: produktionsbereit (Einzelbenutzer) — v0.1.1

• Sprache: Python 3.11+

• Transport: stdio (nativ für Claude Code)

• Basis-URL: https://api.manus.ai

Verifizierte Abdeckung (v0.1.1)

Siehe docs/SECURITY.md und docs/RELEASE.md für den Produktionsablauf.

Was ist enthalten

30 direkte API-Wrapper

3 zusammengesetzte Tools

• manus_file_upload — erstellt eine vorsignierte URL, lädt die Bytes hoch und wartet auf status=uploaded. Akzeptiert path, base64 oder eine öffentliche url.

• manus_task_wait — fragt eine Aufgabe ab, bis sie einen Endstatus erreicht (stopped / waiting / error), und gibt neue Nachrichten sowie Warte-Details (event_id + Antwortschema) zurück.

• manus_website_publish_and_wait — veröffentlicht eine Website und wartet, bis sie published oder failed ist.

3 Webhook-Tools (lesen aus der lokalen SQLite-DB)

• manus_webhook_events_list — listet empfangene Ereignisse mit Filtern auf.

• manus_webhook_events_get — ruft ein Ereignis über event_id ab.

• manus_webhook_events_clear — löscht empfangene Ereignisse.

Gesamt: 36 MCP-Tools.

Installation

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

pip install -e ".[dev]"

API-Schlüssel-Konfiguration

Platzieren Sie eine .env-Datei im Projektstammverzeichnis (eine .env.example-Vorlage wird bereitgestellt). Beide Variablennamen werden akzeptiert:

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

Priorität: process.env > .env.

Optionale Einstellungen:

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

Registrierung bei Claude Code

Fügen Sie Folgendes zu .claude/settings.json (auf Projektebene) oder ~/.claude/settings.json (global) hinzu:

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

Wenn MANUS_API_KEY nicht global gesetzt ist, übergeben Sie ihn explizit:

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

Starten Sie Claude Code neu — die manus_*-Tools erscheinen in der Tool-Liste.

Verifizierung

Ohne den Server zu starten:

python scripts/list_tools.py

Gegen die echte API:

python scripts/smoke.py

Unit-Tests:

pytest

Lint und Typen:

ruff check .
mypy manus_mcp

Nutzungsbeispiele aus Claude Code

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

Die Antwort enthält eine task_id. Dann:

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

Wenn sie fertig ist, erhalten Sie last_assistant_message mit der endgültigen Antwort und new_messages mit dem Gesprächsverlauf.

Hochladen einer Datei und Anhängen an eine Aufgabe:

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

Webhook-Empfänger (optional)

Ein lokaler Empfänger für task_created / task_stopped-Ereignisse mit vollständiger RSA-SHA256-Signaturprüfung gemäß ManusAPIDocs/webhooks/security.md.

1. Umgebungsvariablen konfigurieren

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 muss exakt mit der URL übereinstimmen, die Manus aufruft. Das Manus-Signatur-Payload enthält diese URL, daher führt selbst ein Tippfehler dazu, dass jedes Ereignis abgelehnt wird.

2. Einen Tunnel starten

Zum Beispiel mit Cloudflare Tunnel:

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

oder ngrok:

ngrok http 8787

3. Den Empfänger ausführen

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

4. Den Webhook bei Manus registrieren

In Claude Code:

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

5. Ereignisse lesen

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

Architektur

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

Ratenbegrenzungen

Der Client hält die API-Limits ein (60-Sekunden-Gleitfenster) und wiederholt 429-Antworten transparent mit Backoff + Jitter. Die Limits stammen aus ManusAPIDocs/getting-started/rate-limits.md:

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

• 40/min: alle Mutationen

• 100/min: alle schreibgeschützten Aufrufe

• 600/min: usage.*

Sicherheit

• Der API-Schlüssel wird niemals protokolliert.

• Der Webhook-Empfänger verifiziert Signaturen und lehnt Zeitstempel ab, die älter als 5 Minuten sind.

• Der öffentliche Schlüssel wird für 1 Stunde zwischengespeichert.

• SQLite wird im WAL-Modus mit check_same_thread=False für sicheren Multi-Reader-Zugriff geöffnet.

Lizenz

MIT.