Manus MCP

MCP-сервер, который предоставляет Claude Code полный программный контроль над Manus.im через официальный Manus API v2. Реализует все 30 документированных конечных точек, 3 составных инструмента для типичных рабочих процессов и локальный приемник вебхуков с проверкой подписи RSA-SHA256.

• Статус: готов к работе в продакшене (однопользовательский) — v0.1.1

• Язык: Python 3.11+

• Транспорт: stdio (родной для Claude Code)

• Базовый URL: https://api.manus.ai

Проверенное покрытие (v0.1.1)

См. docs/SECURITY.md и docs/RELEASE.md для ознакомления с процессом выпуска.

Что включено

30 прямых API-оберток

3 составных инструмента

• manus_file_upload — создает предварительно подписанный URL, загружает байты и ожидает status=uploaded. Принимает path, base64 или публичный url.

• manus_task_wait — опрашивает задачу до тех пор, пока она не достигнет терминального статуса (stopped / waiting / error), и возвращает новые сообщения плюс детали ожидания (event_id + схема ответа).

• manus_website_publish_and_wait — публикует сайт и ожидает, пока он не станет published или failed.

3 инструмента для вебхуков (чтение из локальной БД SQLite)

• manus_webhook_events_list — список полученных событий с фильтрами.

• manus_webhook_events_get — получение события по event_id.

• manus_webhook_events_clear — удаление полученных событий.

Всего: 36 инструментов MCP.

Установка

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

pip install -e ".[dev]"

Настройка API-ключа

Разместите файл .env в корне проекта (предоставлен шаблон .env.example). Принимаются оба имени переменных:

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

Приоритет: process.env > .env.

Дополнительные настройки:

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

Регистрация в Claude Code

Добавьте следующее в .claude/settings.json (на уровне проекта) или ~/.claude/settings.json (глобально):

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

Если MANUS_API_KEY не задан глобально, передайте его явно:

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

Перезапустите Claude Code — инструменты manus_* появятся в списке инструментов.

Проверка

Без запуска сервера:

python scripts/list_tools.py

Против реального API:

python scripts/smoke.py

Модульные тесты:

pytest

Линтер и типы:

ruff check .
mypy manus_mcp

Примеры использования из Claude Code

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

Ответ содержит task_id. Затем:

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

Когда задача завершится, вы получите last_assistant_message с финальным ответом и new_messages с историей диалога.

Загрузка файла и прикрепление его к задаче:

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

Приемник вебхуков (опционально)

Локальный приемник для событий task_created / task_stopped с полной проверкой подписи RSA-SHA256 согласно ManusAPIDocs/webhooks/security.md.

1. Настройка переменных окружения

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 должен в точности совпадать с URL, который вызывает Manus. Полезная нагрузка подписи Manus включает этот URL, поэтому даже опечатка приведет к отклонению каждого события.

2. Запуск туннеля

Например, с помощью Cloudflare Tunnel:

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

или ngrok:

ngrok http 8787

3. Запуск приемника

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

4. Регистрация вебхука в Manus

В Claude Code:

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

5. Чтение событий

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

Архитектура

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

Ограничения скорости

Клиент соблюдает лимиты API (скользящее окно 60 секунд) и прозрачно повторяет запросы с кодом 429 с использованием экспоненциальной задержки и джиттера. Лимиты взяты из ManusAPIDocs/getting-started/rate-limits.md:

• 10/мин: task.create, task.sendMessage

• 40/мин: все мутации

• 100/мин: все вызовы только для чтения

• 600/мин: usage.*

Безопасность

• API-ключ никогда не логируется.

• Приемник вебхуков проверяет подписи и отклоняет временные метки старше 5 минут.

• Публичный ключ кэшируется на 1 час.

• SQLite открывается в режиме WAL с check_same_thread=False для безопасного доступа нескольких читателей.

Лицензия

MIT.