Manus MCP

An MCP server that gives Claude Code full programmatic control over Manus.im through the official Manus API v2. Implements all 30 documented endpoints, 3 composite tools for common workflows, and a local webhook receiver with RSA-SHA256 signature verification.

• Status: production-ready (single-user) — v0.1.1

• Language: Python 3.11+

• Transport: stdio (native to Claude Code)

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

Verified coverage (v0.1.1)

See docs/SECURITY.md and docs/RELEASE.md for the production flow.

What's included

30 direct API wrappers

3 composite tools

• manus_file_upload — creates a presigned URL, uploads the bytes, and waits for status=uploaded. Accepts path, base64, or a public url.

• manus_task_wait — polls a task until it reaches a terminal status (stopped / waiting / error) and returns new messages plus wait details (event_id + response schema).

• manus_website_publish_and_wait — publishes a site and waits until it becomes published or failed.

3 webhook tools (read from the local SQLite DB)

• manus_webhook_events_list — list received events with filters.

• manus_webhook_events_get — fetch an event by event_id.

• manus_webhook_events_clear — delete received events.

Total: 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 key configuration

Place a .env file in the project root (a .env.example template is provided). Both variable names are accepted:

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

Priority: process.env > .env.

Optional settings:

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

Registering with Claude Code

Add the following to .claude/settings.json (project-level) or ~/.claude/settings.json (global):

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

If MANUS_API_KEY is not set globally, pass it explicitly:

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

Restart Claude Code — the manus_* tools will appear in the tool list.

Verification

Without launching the server:

python scripts/list_tools.py

Against the real API:

python scripts/smoke.py

Unit tests:

pytest

Lint and types:

ruff check .
mypy manus_mcp

Usage examples from Claude Code

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

The response contains a task_id. Then:

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

When it finishes you get last_assistant_message with the final reply and new_messages with the conversation history.

Uploading a file and attaching it to a task:

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 receiver (optional)

A local receiver for task_created / task_stopped events with full RSA-SHA256 signature verification per ManusAPIDocs/webhooks/security.md.

1. Configure environment variables

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 must exactly match the URL Manus calls. The Manus signing payload includes this URL, so even a typo will cause every event to be rejected.

2. Start a tunnel

For example, with Cloudflare Tunnel:

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

or ngrok:

ngrok http 8787

3. Run the receiver

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

4. Register the webhook with Manus

In Claude Code:

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

5. Read events

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

Architecture

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

Rate limits

The client honours the API limits (60-second sliding window) and transparently retries 429 responses with backoff + jitter. Limits come from ManusAPIDocs/getting-started/rate-limits.md:

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

• 40/min: all mutations

• 100/min: all read-only calls

• 600/min: usage.*

Security

• The API key is never logged.

• The webhook receiver verifies signatures and rejects timestamps older than 5 minutes.

• The public key is cached for 1 hour.

• SQLite is opened in WAL mode with check_same_thread=False for safe multi-reader access.

License

MIT.