Affine MCP Server

🚀 AFFiNE MCP 服务器

AFFiNE MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它能够与自托管或云端的 AFFiNE 实例实现无缝集成。借助该服务器，AI 助手可以通过标准化接口与 AFFiNE 工作区和文档进行交互。

🚀 快速开始

与 Claude Desktop 集成

将以下内容添加到你的 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "affine": {
      "command": "node",
      "args": ["/path/to/affine-mcp-server/dist/index.js"],
      "env": {
        "AFFINE_BASE_URL": "https://your-affine-instance.com",
        "AFFINE_EMAIL": "your@email.com",
        "AFFINE_PASSWORD": "your_password"
      }
    }
  }
}

与 Codebase CLI (codex) 集成

将以下内容添加到你的 Codebase CLI 配置文件中：

{
  "affine": {
    "command": "node",
    "args": ["/path/to/affine-mcp-server/dist/index.js"],
    "env": {
      "AFFINE_BASE_URL": "https://your-affine-instance.com",
      "AFFINE_EMAIL": "your@email.com", 
      "AFFINE_PASSWORD": "your_password"
    }
  }
}

✨ 主要特性

• 工作区管理：可以创建带有初始文档的工作区，并且可通过 UI 进行操作。
• 文档操作：支持列出、搜索和管理文档。
• 用户管理：提供认证和用户资料管理功能。
• 评论系统：具备完整的评论创建、读取、更新和删除操作。
• 版本历史：可查看文档历史记录并进行恢复操作。
• 通知管理：支持读取和管理通知。

📦 安装指南

# 克隆仓库
git clone https://github.com/dawncr0w/affine-mcp-server.git
cd affine-mcp-server

# 安装依赖
npm install

# 构建 TypeScript 代码
npm run build

📚 详细文档

配置

在项目根目录下创建一个 .env 文件：

# AFFiNE 服务器 URL（必需）
AFFINE_BASE_URL=https://your-affine-instance.com

# 认证方式（选择一种）：

# 选项 1：Bearer Token（优先级最高）
AFFINE_API_TOKEN=your_personal_access_token

# 选项 2：会话 Cookie
AFFINE_COOKIE=affine_session=xxx; affine_csrf=yyy

# 选项 3：邮箱/密码（备用）
AFFINE_EMAIL=your@email.com
AFFINE_PASSWORD=your_password

# 可选设置
AFFINE_GRAPHQL_PATH=/graphql  # 默认值：/graphql
AFFINE_WORKSPACE_ID=workspace-uuid  # 操作的默认工作区

认证优先级

服务器按以下顺序检查认证方式：

1. Bearer Token (AFFINE_API_TOKEN) - 优先级最高
2. Cookie (AFFINE_COOKIE)
3. 邮箱/密码 (AFFINE_EMAIL + AFFINE_PASSWORD) - 备用

可用工具

工作区管理（5 个工具）

• list_workspaces - 列出所有可访问的工作区
• get_workspace - 获取工作区详细信息
• create_workspace - 创建带有初始文档的工作区 ✅
• update_workspace - 更新工作区设置
• delete_workspace - 永久删除工作区

文档操作（6 个工具）

• list_docs - 分页列出文档
• get_doc - 获取文档元数据
• search_docs - 按关键字搜索文档
• recent_docs - 列出最近更新的文档
• publish_doc - 使文档公开
• revoke_doc - 撤销文档的公开访问权限

评论（5 个工具）

• list_comments - 列出文档评论
• create_comment - 创建新评论
• update_comment - 更新评论内容
• delete_comment - 删除评论
• resolve_comment - 解决/未解决评论

版本历史（2 个工具）

• list_histories - 查看文档历史记录
• recover_doc - 恢复到之前的版本

用户管理（4 个工具）

• current_user - 获取当前用户信息
• sign_in - 使用邮箱/密码登录
• update_profile - 更新用户资料
• update_settings - 更新用户设置

访问令牌（3 个工具）

• list_access_tokens - 列出个人访问令牌
• generate_access_token - 创建新的访问令牌
• revoke_access_token - 撤销访问令牌

通知（3 个工具）

• list_notifications - 获取通知
• read_notification - 将通知标记为已读
• read_all_notifications - 将所有通知标记为已读

Blob 存储（3 个工具）

• upload_blob - 上传文件/blob
• delete_blob - 删除 blob
• cleanup_blobs - 清理已删除的 blob

高级（1 个工具）

• apply_doc_updates - 将 CRDT 更新应用到文档

测试

# 运行全面测试
node test-comprehensive.mjs

# 测试工作区创建
node test-fixed-workspace.mjs

故障排除

认证问题

1. 邮箱/密码认证失败：
   • 确保你的 AFFiNE 实例允许使用密码认证。
   • 检查与 AFFiNE 服务器的网络连接。
   • 验证凭证是否正确。
2. Cookie 认证：
   • 从浏览器开发者工具的网络选项卡中提取 Cookie。
   • 登录后查找 affine_session Cookie。
   • 将所有相关 Cookie 包含在 AFFINE_COOKIE 中。
3. Token 认证：
   • 从 AFFiNE 用户设置中生成 Token。
   • 确保 Token 未过期。
   • 在 AFFINE_API_TOKEN 中使用完整的 Token 字符串。

连接问题

• 验证 AFFINE_BASE_URL 是否可访问。
• 检查 GraphQL 端点是否为 /graphql（默认值）。
• 确保没有防火墙或代理阻止连接。
• 对于自托管实例，验证 CORS 设置。

安全注意事项

• 切勿提交包含凭证的 .env 文件。
• 在生产环境中使用环境变量。
• 定期轮换访问令牌。
• 始终使用 HTTPS 进行 AFFiNE 连接。
• 将凭证存储在安全的凭证管理器中。

版本历史

1.1.0 (2025-08-12)

• ✅ 修复了创建带有初始文档的工作区的问题。
• 添加了 30 多个用于全面管理 AFFiNE 的工具。
• 现在可以通过 UI 创建工作区。
• 改进了错误处理和认证机制。
• 简化了工具名称，提高了可用性。

1.0.0 (2025-08-12)

• 初始稳定版本。
• 支持基本的工作区和文档操作。
• 提供完整的认证支持。

贡献

欢迎贡献代码！请按照以下步骤进行：

1. 分叉仓库。
2. 创建功能分支。
3. 为新功能添加测试。
4. 确保所有测试通过。
5. 提交拉取请求。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

如有问题或疑问：

• 在 GitHub 上提交问题。
• 查看 AFFiNE 文档：https://docs.affine.pro

作者

dawncr0w - GitHub

致谢

• 为 AFFiNE 知识库平台构建。
• 使用 Model Context Protocol 规范。
• 由 @modelcontextprotocol/sdk 提供支持。