布罗肯克劳
一个为AI代理提供帮助的集成服务器。Brokenclaw通过统一的REST API和117个MCP工具公开了18个外部平台-让Claude、GPT和其他LLM读取您的电子邮件、搜索Google Drive、发布到Slack、管理GitHub问题等等，所有这些都来自一个本地主机服务器。
┌─────────────────────────────────────────────────────┐
│ AI Agent │
│ (Claude, GPT, etc.) │
└──────────────┬──────────────────┬───────────────────┘
│ MCP (tools) │ REST API
▼ ▼
┌─────────────────────────────────────────────────────┐
│ Brokenclaw │
│ localhost:9000 · single process │
│ │
│ ┌─────────┐ ┌──────────┐ ┌───────────────────┐ │
│ │ OAuth │ │ API Keys │ │ Session Cookies │ │
│ │ (Google) │ │ │ │ (Playwright auth) │ │
│ └────┬─────┘ └────┬─────┘ └────────┬──────────┘ │
│ ▼ ▼ ▼ │
│ Gmail Drive GitHub News LinkedIn Instagram │
│ Sheets Docs Maps Wolfram Canvas Slack │
│ Slides Tasks YouTube │
│ Forms Calendar │
│ Gemini │
└─────────────────────────────────────────────────────┘特性
- 117个MCP工具 --每个集成都作为AI代理的可调用工具公开
- 123个REST端点 -完整的HTTP API和OpenAPI文档位于
/docs - 多账户 --每次集成连接多个帐户（例如个人+工作Gmail）
- 仅限本地主机 --中间件拒绝所有非127.0.0.1请求
- 三种身份验证策略 -OAuth2、API密钥和基于浏览器的会话Cookie
- 自动刷新令牌 --OAuth令牌透明刷新；无需手动重新认证
- 结构化错误 --MCP工具返回对代理友好的错误字典，并给出建议操作
集成
谷歌OAuth（9个集成）
| 集成 | 它能做什么 |
|---|---|
| Gmail | 收件箱、搜索、阅读完整邮件、发送、回复、修改标签 |
| 驾驶 | 列出、搜索、读取、创建文件和文件夹 |
| 表格 | 读取/写入单元格范围、追加行、创建电子表格 |
| 文档 | 阅读内容、创建文档、插入文本、查找/替换 |
| 幻灯片 | 阅读演示文稿、创建演示文稿、添加幻灯片、查找/替换 |
| 任务 | 任务列表，创建/更新/完成/删除任务 |
| 表单 | 创建表单、添加问题、阅读回复 |
| 油管 | 搜索视频，获取视频/频道详细信息，列出播放列表 |
| 日历 | 列出/创建/更新/删除事件，快速添加 |
基于API密钥和提要（6个集成）
| 集成 | 它能做什么 |
|---|---|
| 地图/天气/时区 | 地理代码、方向、附近地点、当前天气、预报、时区查找 |
| 新闻 | 热门标题，按关键字/来源/日期搜索文章 |
| GitHub | repo、问题、PR、通知、代码搜索 |
| 知识引擎 | 结构化查询，简短答案——数学、科学、事实 |
| Canvas LMS | 课程、作业、成绩、公告、待办事项、个人资料（+iCal feed） |
| 双子座 | 通过谷歌的Gemini模型分析来自任何平台URL的图像和视频 |
基于会话Cookie（3个集成）
这些使用Playwright自动登录浏览器，然后通过私有API进行操作。
| 集成 | 它能做什么 |
|---|---|
| 领英 | 个人资料、订阅源、连接、对话、消息、通知、搜索人员/公司/工作 |
| 个人资料、订阅源、帖子、故事、转轴、关注者/追随者、已保存、DM、搜索、探索 | |
| Slack | 个人资料、对话、消息、帖子、搜索、用户 |
快速开始
先决条件
- Python 3.11+
- A. 谷歌云控制台 使用您希望启用的API进行项目
- 用于要使用的任何基于密钥的集成的API密钥
安装
git clone https://github.com/yourname/brokenclaw.git
cd brokenclaw
python -m venv .venv
source .venv/bin/activate
pip install -e .
playwright install chromium # needed for LinkedIn, Instagram, Slack, Canvas auth配置
- 下载
client_secret.json从谷歌云控制台（OAuth 2.0客户端ID， Web应用程序 type）并将其放置在项目根目录中。
- 创建一个
.env文件：
# Google API key integrations
GOOGLE_MAPS_API_KEY=your-key
GEMINI_API_KEY=your-key
# Third-party API keys
NEWS_API_KEY=your-key
GITHUB_TOKEN=ghp_your-token
WOLFRAM_APP_ID=your-app-id
# Canvas LMS
CANVAS_BASE_URL=https://your-school.instructure.com
CANVAS_FEED_URL=https://your-school.instructure.com/feeds/calendars/...
# LinkedIn (for browser-based auth)
LINKEDIN_USERNAME=you@email.com
LINKEDIN_PASSWORD=your-password
# Instagram (for browser-based auth)
INSTAGRAM_USERNAME=your-username
INSTAGRAM_PASSWORD=your-password
# Slack (for browser-based auth)
SLACK_WORKSPACE_URL=https://your-workspace.slack.com
SLACK_EMAIL=you@email.com
SLACK_PASSWORD=your-password- 在Google Cloud Console中为每个Google集成添加OAuth重定向URI：
http://localhost:9000/auth/gmail/callback
http://localhost:9000/auth/drive/callback
http://localhost:9000/auth/sheets/callback
...跑
source .venv/bin/activate
uvicorn brokenclaw.main:app --host 127.0.0.1 --port 9000或者使用Docker：
docker compose up验证
谷歌集成 --请访问浏览器中的设置URL：
http://localhost:9000/auth/gmail/setup
http://localhost:9000/auth/drive/setup
...完成OAuth流程一次。之后令牌会自动刷新。
基于会话的集成 --访问设置URL，然后在Playwright浏览器中完成登录：
http://localhost:9000/auth/linkedin/setup
http://localhost:9000/auth/instagram/setup
http://localhost:9000/auth/slack/setup
http://localhost:9000/auth/canvas/setup检查状态 在所有集成中：
GET http://localhost:9000/api/status使用AI代理
克劳德代码（MCP）
添加到MCP设置(~/.claude/settings.json 或项目 .mcp.json):
{
"mcpServers": {
"brokenclaw": {
"url": "http://localhost:9000/mcp"
}
}
}然后，Claude可以调用以下工具 gmail_inbox, drive_search, github_list_issues等等。
REST API
所有集成都可以作为标准HTTP端点使用：
# Read your inbox
curl http://localhost:9000/gmail/inbox
# Search Google Drive
curl "http://localhost:9000/drive/search?query=quarterly%20report"
# Send an email
curl -X POST http://localhost:9000/gmail/send \
-H "Content-Type: application/json" \
-d '{"to": "alice@example.com", "subject": "Hello", "body": "Hi from Brokenclaw"}'
# Check GitHub notifications
curl http://localhost:9000/github/notifications交互式API文档可在 http://localhost:9000/docs.
建筑
brokenclaw/
├── main.py # Starlette root app — mounts FastAPI + FastMCP
├── mcp_server.py # 117 MCP tool definitions
├── auth.py # OAuth2 flows + token persistence
├── config.py # pydantic-settings, reads .env
├── exceptions.py # AuthenticationError, IntegrationError, RateLimitError
├── http_client.py # Shared HTTP client utilities
├── models/ # Pydantic models per integration
├── services/ # Business logic (shared by REST + MCP)
│ ├── gmail.py
│ ├── drive.py
│ ├── linkedin_auth.py # Playwright-based browser auth
│ ├── linkedin_client.py # Voyager API client (curl_cffi)
│ └── ...
├── routers/ # REST endpoints per integration
│ ├── gmail.py
│ ├── drive.py
│ └── ...
tests/ # Integration tests per service服务层是真理的源泉。REST路由器和MCP工具是委托给服务的瘦包装器，将业务逻辑保存在一个地方。
测试
pip install -e ".[test]"
pytest测试涉及真实的外部API，需要主动身份验证。使用pytest标记运行特定的集成测试：
pytest tests/test_gmail.py
pytest tests/test_github.py许可证
私人项目。保留所有权利。