manus-mcp 0.1.1

MCP server exposing the full Manus API v2 surface to Claude Code

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)

Layer	Metric
Unit tests	60+ (server.py dispatch, webhook ASGI app, secret-leak guard, schema stability)
Live e2e tests	23 (including task.update / sendMessage / confirmAction / agent.update / website.publish)
Composite live	4 (including the F2 reject check)
Webhook live e2e	1 (cloudflared tunnel + receiver + Manus delivery)
Manus API endpoints exercised live	30/30 (graceful skip only when the account lacks the prerequisite — no agents / no website)
Coverage	≥ 80% (gated in CI)
mypy --strict	0 errors
ruff check	0 errors

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

What's included

30 direct API wrappers

Category	Tools
Tasks (9)	manus_task_create, manus_task_detail, manus_task_list, manus_task_update, manus_task_stop, manus_task_delete, manus_task_send_message, manus_task_list_messages, manus_task_confirm_action
Projects (2)	manus_project_create, manus_project_list
Skills (1)	manus_skill_list
Agents (3)	manus_agent_list, manus_agent_detail, manus_agent_update
Files (3)	manus_file_create, manus_file_detail, manus_file_delete
Webhooks (4)	manus_webhook_create, manus_webhook_list, manus_webhook_delete, manus_webhook_public_key
Usage (3)	manus_usage_list, manus_usage_team_statistic, manus_usage_team_log
Connectors (1)	manus_connector_list
Browser (1)	manus_browser_online_list
Website (3)	manus_website_status, manus_website_list_checkpoints, manus_website_publish

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.