Manus MCP

Live

공식 Manus API v2를 통해 Claude Code가 Manus.im을 완전히 프로그래밍 방식으로 제어할 수 있도록 하는 MCP 서버입니다. 문서화된 30개의 모든 엔드포인트, 일반적인 워크플로우를 위한 3개의 복합 도구, 그리고 RSA-SHA256 서명 검증을 포함한 로컬 웹훅 수신기를 구현합니다.

상태: 프로덕션 준비 완료 (단일 사용자) — v0.1.1
언어: Python 3.11+
전송: stdio (Claude Code 기본)
기본 URL: https://api.manus.ai

검증된 커버리지 (v0.1.1)

계층	지표
단위 테스트	60개 이상 (server.py 디스패치, 웹훅 ASGI 앱, 비밀 키 유출 방지, 스키마 안정성)
라이브 e2e 테스트	23개 (task.update / sendMessage / confirmAction / agent.update / website.publish 포함)
복합 라이브	4개 (F2 거부 확인 포함)
웹훅 라이브 e2e	1개 (cloudflared 터널 + 수신기 + Manus 전달)
라이브로 실행된 Manus API 엔드포인트	30/30 (계정에 필수 조건이 없는 경우에만 정상적으로 건너뜀 — 에이전트 없음 / 웹사이트 없음)
커버리지	≥ 80% (CI에서 제한)
`mypy --strict`	0 오류
`ruff check`	0 오류

프로덕션 흐름은 docs/SECURITY.md 및 docs/RELEASE.md를 참조하세요.

포함된 기능

30개의 직접 API 래퍼

카테고리	도구
작업 (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`
프로젝트 (2)	`manus_project_create`, `manus_project_list`
기술 (1)	`manus_skill_list`
에이전트 (3)	`manus_agent_list`, `manus_agent_detail`, `manus_agent_update`
파일 (3)	`manus_file_create`, `manus_file_detail`, `manus_file_delete`
웹훅 (4)	`manus_webhook_create`, `manus_webhook_list`, `manus_webhook_delete`, `manus_webhook_public_key`
사용량 (3)	`manus_usage_list`, `manus_usage_team_statistic`, `manus_usage_team_log`
커넥터 (1)	`manus_connector_list`
브라우저 (1)	`manus_browser_online_list`
웹사이트 (3)	`manus_website_status`, `manus_website_list_checkpoints`, `manus_website_publish`

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 DB에서 읽기)

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

웹훅 수신기 (선택 사항)

ManusAPIDocs/webhooks/security.md에 따른 전체 RSA-SHA256 서명 검증을 포함하는 task_created / task_stopped 이벤트용 로컬 수신기입니다.

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은 Manus가 호출하는 URL과 정확히 일치해야 합니다. 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 응답을 받으면 백오프 + 지터(jitter)를 사용하여 투명하게 재시도합니다. 제한 사항은 ManusAPIDocs/getting-started/rate-limits.md에서 가져옵니다:

10/분: task.create, task.sendMessage
40/분: 모든 변경 작업
100/분: 모든 읽기 전용 호출
600/분: usage.*

보안

API 키는 절대 로그에 기록되지 않습니다.
웹훅 수신기는 서명을 검증하고 5분이 지난 타임스탬프는 거부합니다.
공개 키는 1시간 동안 캐시됩니다.
SQLite는 안전한 다중 읽기 액세스를 위해 check_same_thread=False와 함께 WAL 모드로 열립니다.

라이선스

MIT.

Manus MCP

Manus MCP

검증된 커버리지 (v0.1.1)

포함된 기능

30개의 직접 API 래퍼

3개의 복합 도구

3개의 웹훅 도구 (로컬 SQLite DB에서 읽기)

설치

API 키 구성

Claude Code에 등록

검증

Claude Code 사용 예시

웹훅 수신기 (선택 사항)

1. 환경 변수 구성

2. 터널 시작

3. 수신기 실행

4. Manus에 웹훅 등록

5. 이벤트 읽기

아키텍처

속도 제한

보안

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API