内容
<p align="center">
<img src="assets/social-preview.png" alt="AppFlowy MCP 服务器" width="840">
</p>
# AppFlowy MCP 服务器
<div align="center">
[](https://github.com/Rahulk644/appflowy-mcp-server/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
</div>
一个开源的 **[模型上下文协议](https://modelcontextprotocol.io) 服务器，为 [AppFlowy 云](https://appflowy.com)** 提供服务 — 让 AI 代理可以 **读取、构建和完成** 您 AppFlowy 工作空间中的工作。
不仅仅是 *查看* 看板：创建数据库和页面、移动卡片、编辑和删除行，以及编辑文档块（包括调用和切换等高级块）— 所有操作都通过单个端点，该端点 **限定于您选择的特定工作空间**，并由 **谷歌身份验证或令牌** 控制。
> ℹ️ 独立的社区项目 — 不隶属于 AppFlowy，也不得到 AppFlowy 的认可。它通过您控制的帐户与公共 AppFlowy 云 API 进行通信。
## ✨ 亮点
- **完整的 CRUD，而非只读。** 创建页面/数据库/字段/行，并通过协作编辑（CRDT）层 **编辑、移动和删除** 任意现有的行或文档块，包括用户界面手动创建的块。
- **REST API 无法创建的高级块。** 调用、切换、引用、代码、列等，可通过编程方式放置。
- **设计限定范围。** `ALLOWED_WORKSPACE_IDS` 使得每个工具都拒绝 allow-list 之外的任何内容 — 即使帐户可以查看更多内容。
- **三种连接方式。** 谷歌 **OAuth 登录**、Bearer **头部** 令牌或 URL 链接中的令牌（适用于无法设置头部的 UI）。适用于 Claude、Cursor、Antigravity 和任何 MCP 客户端。
- **代理就绪。** 随服务器附带 AppFlowy “知识包”，作为 MCP 服务器指令（参见 [KNOWLEDGE.md](KNOWLEDGE.md)），以便代理构建干净、结构良好的内容。
- **功能齐全。** 包括 stdio / Streamable-HTTP / SSE 传输、Docker、测试和持续集成。
## 🧰 工具
**读取** — `get_workspaces`, `get_workspace_folder`, `list_databases`, `get_database_fields`, `get_database_row_ids`, `get_database_row_details`, `get_page`, `list_updated_rows`
**创建和结构化**（纯 JSON，无 CRDT）— `create_page`, `create_database` （网格/看板/日历），`create_database_view`, `add_database_field`, `create_database_row`, `upsert_database_row`, `append_blocks`, `create_space`, `move_page`, `duplicate_page`, `trash_page`
**编辑和删除 — 任意行或块**（协作/CRDT 层）— `update_row_cells` （例如，通过设置状态移动看板卡片），`delete_row`, `add_block` （包括调用/切换/引用/代码等高级块），`edit_block_text`, `delete_block`
卡片/行正文支持 **Markdown**，渲染成真正的块（标题、列表、交互式复选框、表格、代码、数学公式）。字段类型 ID、页面块树模式和完整的块调色板均在 [KNOWLEDGE.md](KNOWLEDGE.md) 中有文档。
## 🏗️ 工作原理
```
MCP 客户端 此服务器 AppFlowy 云
（Claude、Cursor、 ── OAuth / ──► （您托管） ── 机器人 ──► （您的工作空间）
Antigravity …) 令牌 帐户
├─ REST API .......... 读取、创建页面/数据库/字段/行、追加块、Markdown 文档
└─ 协作/CRDT（pycrdt） 编辑/移动/删除任意行或块、高级块
```
服务器使用 **专用机器人帐户** 登录 AppFlowy 云，并公开 MCP 工具。大多数操作使用 JSON REST API；精确编辑/删除和高级块通过 AppFlowy 的协作（Yjs/CRDT）层进行合并更新，因此它们在实时编辑时是安全的。
## 🚀 快速开始
### 本地（stdio）— 最私密，无需暴露
```bash
cp .env.example .env # 填写 APPFLOWY_EMAIL / APPFLOWY_PASSWORD
pip install -r requirements.txt
python server.py
```
### Docker / VPS — 适用于远程和无人值守的代理
```bash
cp .env.example .env # 填写凭证 + MCP_SECRET_TOKEN（和 OAuth，可选）
docker compose up -d --build
```
`docker-compose.yaml` 包含可选的 Traefik 标签。**请勿将端口暴露在开放的互联网上** — 使用身份验证门户（例如 Cloudflare Tunnel + Access）或内置身份验证进行前端防护。包含一个引导脚本 `deploy_vps.sh`，用于首次部署。
## ⚙️ 配置（`.env`）
| 变量 | 必需 | 备注 |
|---|---|---|
| `APPFLOWY_EMAIL` / `APPFLOWY_PASSWORD` | ✅ | 专用机器人帐户登录。 |
| `APPFLOWY_BASE_URL` | – | 默认值为 `https://beta.appflowy.cloud`。 |
| `ALLOWED_WORKSPACE_IDS` | 强烈建议 | 服务器可以触及的以逗号分隔的工作空间 ID。 |
| `MCP_SECRET_TOKEN` | 用于网络 | 共享令牌；`openssl rand -hex 32`。 |
| `MCP_ALLOWED_HOSTS` / `MCP_ALLOWED_ORIGINS` | 当被代理时 | 您的公共主机（DNS 重绑定保护）。 |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | 用于 OAuth | 启用谷歌登录（参见下文）。 |
| `ALLOWED_EMAILS` | 用于 OAuth | 允许登录的以逗号分隔的电子邮件。 |
| `OAUTH_ISSUER` | 用于 OAuth | 公共基本 URL，例如 `https://mcp.example.com`。 |
## 🔌 连接客户端
**谷歌 OAuth** *(推荐用于远程/共享使用 — 链接中无令牌)*
1. 创建谷歌 OAuth **网络** 客户端；将重定向 URI 设置为 `https://YOUR_HOST/auth/google/callback`。
2. 设置 `GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET`、`ALLOWED_EMAILS`、`OAUTH_ISSUER` 并重启。
3. 在您的 MCP 客户端中，添加一个自定义连接器，仅使用 URL `https://YOUR_HOST/mcp/` — 它将触发谷歌登录。
**Bearer 头部** *(技术客户端 / 命令行接口)*
```json
{ "mcpServers": { "appflowy": {
"url": "https://mcp.example.com/mcp/",
"headers": { "Authorization": "Bearer YOUR_MCP_SECRET_TOKEN" }
}}}
```
对于仅限 stdio 的客户端，请使用 `npx mcp-remote https://mcp.example.com/mcp/ --header "Authorization: Bearer YOUR_MCP_SECRET_TOKEN"` 进行桥接。
**链接（URL 中的令牌）** *(适用于无法设置头部的 UI)*
```
https://mcp.example.com/mcp/?token=YOUR_MCP_SECRET_TOKEN
```
方便，但令牌位于 URL/日志中 — 请像密码一样保护整个链接。
**本地（stdio）**
```json
{ "mcpServers": { "appflowy": { "command": "python", "args": ["/absolute/path/to/server.py"] } } }
```
## 🔐 安全
AppFlowy 云身份验证是全帐户（没有 **限定范围的 API 密钥**），因此：
- 使用 **专用机器人帐户**，仅邀请到您公开的工作空间。
- 设置 **`ALLOWED_WORKSPACE_IDS`** — 在每个工具上强制执行。
- 使用 **OAuth**（电子邮件允许列表）或 **`MCP_SECRET_TOKEN`** 保护端点，并将端口保持在开放的互联网之外。
完整详细信息和漏洞报告：[SECURITY.md](SECURITY.md)。
## 🧪 开发
```bash
pip install -r requirements.txt
ruff format . && ruff check .
pytest -q
```
持续集成在每次推送/拉取请求时运行 lint、格式检查和测试。
## 🧭 比较
[`LucasXu0/appflowy_mcp`](https://github.com/LucasXu0/appflowy_mcp) 涵盖了页面/文件夹/回收站/收藏。 本服务器添加了 **数据库写回、全行/块编辑和删除（通过协作层）、工作空间范围和 OAuth** — 适用于 **完成** 而非只是读取看板的代理。
## 🗺️ 路线图
- 持久的 OAuth 令牌存储（在重启时存活，无需重新身份验证）
- 调度摄取配方（例如会议笔记 → 看板）
- 协作编辑中的更丰富的内联格式
## 🤝 贡献
欢迎贡献 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
## 📄 许可证
[MIT](LICENSE)。
