内容
# Manus MCP
[](https://pypi.org/project/manus-mcp/)
[](https://pypi.org/project/manus-mcp/)
[](https://pypistats.org/packages/manus-mcp)
[](https://github.com/aruxojuyu665/Manus-MCP/blob/main/LICENSE)
[](https://github.com/aruxojuyu665/Manus-MCP/actions/workflows/ci.yml)
[](https://github.com/aruxojuyu665/Manus-MCP/actions/workflows/live.yml)
[](https://github.com/aruxojuyu665/Manus-MCP/stargazers)
一个 MCP 服务器，为 Claude Code 提供对 Manus.im 的完全程序控制，支持官方 Manus API v2。实现了 **所有 30 个已文档化的端点**、**3 个用于常见工作流的复合工具** 和一个 **本地 webhook 接收器**，具有 RSA-SHA256 签名验证。
- **状态**：生产就绪（单用户）- v0.1.1
- 语言：Python 3.11+
- 传输：stdio（原生于 Claude Code）
- 基地址：`https://api.manus.ai`
## 验证覆盖率（v0.1.1）
| 层 | 指标 |
|------|---------|
| 单元测试 | 60+（server.py 调度，webhook ASGI 应用，秘密泄漏保护，模式稳定性） |
| 实时端到端测试 | 23（包括 task.update / sendMessage / confirmAction / agent.update / website.publish） |
| 复合实时 | 4（包括 F2 拒绝检查） |
| Webhook 实时端到端 | 1（cloudflared 隧道 + 接收器 + Manus 交付） |
| **已演练的 Manus API 端点** | **30/30**（仅当帐户缺少前提条件时才会优雅跳过 - 没有代理 / 没有网站） |
| 覆盖率 | ≥ 80%（在 CI 中控制） |
| `mypy --strict` | 0 错误 |
| `ruff check` | 0 错误 |
参见 [docs/SECURITY.md](docs/SECURITY.md) 和 [docs/RELEASE.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` |
| Webhooks（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 个 webhook 工具（从本地 SQLite DB 读取）
- `manus_webhook_events_list` - 列出接收到的事件并过滤。
- `manus_webhook_events_get` - 通过 `event_id` 获取事件。
- `manus_webhook_events_clear` - 删除接收到的事件。
总计：**36 个 MCP 工具**。
## 安装
```bash
pip install manus-mcp
```
这会从 PyPI 拉取包。`manus-mcp` 和 `manus-mcp-webhook` 控制台脚本变得可用，加上 `python -m manus_mcp` 和 `python -m manus_mcp.webhook_receiver` 模块入口点。
### 从源代码（适用于贡献者）
```bash
git clone https://github.com/aruxojuyu665/Manus-MCP.git
cd Manus-MCP
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
# source .venv/bin/activate
pip install -e ".[dev]"
```
## API 密钥配置
在项目根目录中放置一个 `.env` 文件（提供了一个 `.env.example` 模板）。两个变量名称都被接受：
```env
MANUS_API_KEY=sk-...
# 或，为了向后兼容：
# ManusAPI=sk-...
```
优先级：`process.env` > `.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`（全局）：
```json
{
"mcpServers": {
"manus": {
"command": "python",
"args": ["-m", "manus_mcp"],
"cwd": "path/to/Manus-MCP"
}
}
}
```
如果未全局设置 `MANUS_API_KEY`，请显式传递：
```json
{
"mcpServers": {
"manus": {
"command": "python",
"args": ["-m", "manus_mcp"],
"cwd": "path/to/Manus-MCP",
"env": { "MANUS_API_KEY": "sk-..." }
}
}
}
```
重启 Claude Code - `manus_*` 工具将出现在工具列表中。
## 验证
无需启动服务器：
```bash
python scripts/list_tools.py
```
对抗真实 API：
```bash
python scripts/smoke.py
```
单元测试：
```bash
pytest
```
检查和类型：
```bash
ruff check .
mypy manus_mcp
```
## 来自 Claude Code 的使用示例
```
manus_task_create { "message": { "content": "给我一个今日 AI 新闻的 5 点总结" } }
```
响应包含一个 `task_id`。然后：
```
manus_task_wait { "task_id": "<id>", "timeout_sec": 600 }
```
当它完成时，您将获得 `last_assistant_message` 和包含对话历史的新消息。
上传文件并将其附加到任务：
```
manus_file_upload { "source": { "path": "C:/docs/report.pdf" } }
manus_task_create {
"message": {
"content": [
{ "type": "text", "text": "总结此报告" },
{ "type": "file", "file_id": "<file_id>" }
]
}
}
```
## Webhook 接收器（可选）
一个用于 `task_created` / `task_stopped` 事件的本地接收器，具有完整的 RSA-SHA256 签名验证，按照 `ManusAPIDocs/webhooks/security.md`。
### 1. 配置环境变量
```env
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=... # 默认情况下为 Windows 上的 %LOCALAPPDATA%\manus-mcp\events.db
```
`MANUS_WEBHOOK_PUBLIC_URL` **必须与** Manus 调用的 URL **完全匹配**。Manus 签名有效载体包括此 URL，因此即使是错别字也会导致每个事件都被拒绝。
### 2. 启动隧道
例如，使用 Cloudflare Tunnel：
```bash
cloudflared tunnel --url http://localhost:8787
```
或 ngrok：
```bash
ngrok http 8787
```
### 3. 运行接收器
```bash
python -m manus_mcp.webhook_receiver
# 或：manus-mcp-webhook --host 127.0.0.1 --port 8787
```
### 4. 在 Manus 中注册 webhook
在 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 入口点
├── server.py # MCP 服务器引导
├── config.py # pydantic-settings
├── logger.py # 仅 stderr 日志
├── client/
│ ├── manus_client.py # 异步 httpx 客户端 + 重试
│ ├── rate_limiter.py # 按端点令牌桶（来自 rate-limits.md）
│ ├── retry.py # 指数退避 + 抖动
│ └── errors.py # ManusApiError / ManusNetworkError
├── schemas/ # 每个资源的 pydantic 模型（任务，项目，...）
├── tools/ # 所有 36 个工具的 @manus_tool 注册
│ ├── 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 # 使用 {ts}.{url}.{sha256_hex(body)} 的 RSA-SHA256 验证
├── 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 密钥。
- Webhook 接收器验证签名并拒绝时间戳超过 5 分钟的事件。
- 公钥缓存 1 小时。
- SQLite 以 WAL 模式打开，`check_same_thread=False` 以实现安全的多读取器访问。
## 许可证
MIT.
