AFFiNE MCP 服务器

关键词

AFFiNE工作区管理文档协作实时编辑远程接口

使用说明

  • 项目简介
    • 这是一个基于 Model Context Protocol (MCP) 的后端服务器，专门为 AFFiNE 提供对外的上下文服务。它可以托管 AFFiNE 的工作区和文档、注册并执行工具、定义并渲染 Prompt 模板，并通过 JSON-RPC 的 MCP 客户端与 AI 模型进行交互。支持本地 stdio 连接以及远程 HTTP/Streamable HTTP 连接，方便在本地或云端进行部署与集成。
  • 主要功能点
    • 工作区与文档管理：列出、创建、读取、修改、删除工作区与文档，支持标签、版本历史、导出/导入等。
    • 数据与协作：通过 AFFiNE 的 GraphQL 后端获取元数据，使用 WebSocket/流式传输实现文档协作、 Blob 存储等能力。
    • 工具集成：提供大量用于查询、修改、创建文档、工作区及相关资源的工具（如列表、创建/更新文档、读取文档、标签管理、数据库操作、图片/文件上传、用户与会话等）。
    • Prompt 与模板：为 LLM 提供可定制的提示模板和渲染能力，支持将 AFFiNE 内容转换为可用于对话的上下文。
    • 安全与部署：支持 Token、Cookie、或 Email/Password 等多种身份认证方式，提供 HTTP 端点（/mcp）以及 SSE/原始 SSE 的向后兼容路径，包含 CORS、会话管理与健康诊断输出。
  • 安装步骤
    1. 全局安装（推荐）: 使用 npm 全局安装后即可直接运行 CLI：npm i -g affine-mcp-server
    2. 或通过 npx 直接执行：npx -y -p affine-mcp-server affine-mcp
    3. 构建并运行源代码：
      • 复制仓库后执行 npm install
      • 执行 npm run build
      • 运行 Node.js 产物：node dist/index.js
    4. 运行后默认通过 stdio 与客户端通信；也可开启 HTTP 传输，暴露 /mcp、/sse、/messages 等端点。
  • 服务器配置
    • MCP 客户端需要提供一个启动配置（包含服务名称、启动命令与参数等），以便自动化引导 MCP 服务器。以下为符合实际使用场景的配置要点（以 JSON 表达，便于 MCP 客户端读取）：
    • server name: affine
    • command: affine-mcp
    • args: 该服务器默认作为本地进程运行时不需要额外参数，若需要自定义传输模式可通过环境变量配置，例如开启 HTTP 传输时需设置 MCP_TRANSPORT=http 并提供端口等参数
    • 说明：客户端通常使用配置中的 command 启动服务器进程，例如在 Claude、Cursor、Codex 等集成中指向 affine-mcp；环境变量用于在服务器端控制行为（如 AFFINE_BASE_URL、AFFINE_API_TOKEN、AFFINE_MCP_HTTP_TOKEN、MCP_TRANSPORT 等）
    • 具体常用环境变量（示例，不需要客户端关注）：
      • MCP_TRANSPORT=stdio（默认）或 http/streamable/sse（HTTP 传输）
      • AFFINE_BASE_URL=https://app.affine.pro
      • AFFINE_API_TOKEN=你的访问令牌
      • AFFINE_COOKIE=会话 Cookie（若使用 Cookie 认证）
      • AFFINE_EMAIL/AFFINE_PASSWORD（用于邮箱/密码认证，推荐自托管使用）
      • AFFINE_MCP_HTTP_HOST、AFFINE_MCP_HTTP_TOKEN、AFFINE_MCP_HTTP_ALLOWED_ORIGINS、AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS（HTTP 模式下的安全设置）
    • 额外说明：仓库提供了两种传输模式的实现（stdio 与 HTTP/ SSE），以及兼容的初始化流程和健康诊断日志，确保在云端或本地环境中都能稳定启动。
  • 基本使用方法
    • 连接方式：使用 MCP 客户端（如 Claude Code、Cursor、Codex、或自定义客户端）通过 MCP 协议与服务器对接，读取资源、调用工具、执行提示模板。
    • 常用操作步骤（简要）：
      • 启动 AFFiNE MCP 服务器（命令在客户端配置中指定）；
      • 在客户端配置中指向服务器的命令与必要环境变量；
      • 使用工具进行文档/工作区的查询和操作；如读取文档、创建文档、执行数据库操作、上传 Blob 等；
      • 根据需要通过远程 HTTP /mcp 端点进行云端交互，注意绑定主机和添加访问令牌等安全设置。
    • 运行后可通过日志查看初始化状态、认证状态和工作区信息，确保服务器已经正常对外暴露相应的 MCP 服务端点。

服务器信息

访问项目