AFFiNE MCP Server

AFFiNE MCP服务器

AFFiNE的模型上下文协议（MCP）服务器。它通过stdio（默认）或HTTP向AI助手公开AFFiNE工作区和文档(/mcp)并支持AFFiNE Cloud和自托管部署。

](https://github.com/dawncr0w/affine-mcp-server/releases)   

目录

• 概述
• 选择你的道路
• 快速开始
• 兼容性矩阵
• 刀具表面
• 文档地图
• 验证您的设置
• 安全和范围
• 发展
• 发布说明
• 许可证
• 支持

概述

AFFiNE MCP服务器设计用于三种常见场景：

• 为Claude Code、Codex CLI、Cursor或Claude Desktop运行本地stdio MCP服务器
• 为托管或浏览器连接的客户端公开远程HTTP MCP端点
• 通过稳定的MCP工具界面自动化AFFiNE工作区、文档、数据库、组织和评论工作流

亮点：

• 支持AFFiNE Cloud和自托管AFFiNE实例
• 支持stdio和HTTP传输
• 支持令牌、cookie和电子邮件/密码身份验证
• 公开了84个由AFFiNE GraphQL和WebSocket API支持的规范MCP工具
• 包括语义页面组合、本机模板实例化、数据库意图组合、能力和保真度报告以及工作区蓝图助手
• 包括Docker镜像、健康探测和端到端测试覆盖率

范围边界：

• 此服务器只能访问服务器支持的AFFiNE工作区
• 仅存储在本地存储中的浏览器本地工作区无法通过AFFiNE服务器API访问
• AFFiNE云需要基于API的访问才能使用MCP；Cloudflare阻止了程序化电子邮件/密码登录

v2.0.0中的新功能：添加了本机无边缘画布工具，并发布了更精简的84工具公共界面，具有只读、核心和创作部署的最低权限配置文件。

选择你的道路

快速开始

1.安装CLI

npm i -g affine-mcp-server
affine-mcp --version

您还可以临时运行该包：

npx -y -p affine-mcp-server affine-mcp -- --version

2.或者在Docker中运行服务器

docker run -d \
  -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e AFFINE_BASE_URL=https://your-affine-instance.com \
  -e AFFINE_API_TOKEN=ut_your_token \
  -e AFFINE_MCP_AUTH_MODE=bearer \
  -e AFFINE_MCP_HTTP_TOKEN=your-strong-secret \
  ghcr.io/dawncr0w/affine-mcp-server:latest

然后将您的客户指向：

{
  "mcpServers": {
    "affine": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-strong-secret"
      }
    }
  }
}

有关Docker、健康检查和远程部署的详细信息，请参阅 .

3.使用交互式登录保存凭据

affine-mcp login

此操作将凭据存储在 ~/.config/affine-mcp/config 带模式 600.

• 对于AFFiNE Cloud，请使用中的API令牌 Settings -> Integrations -> MCP Server
• 对于自托管AFFiNE，您可以使用API令牌或电子邮件/密码

4.在客户端注册服务器

Claude Code项目配置：

{
  "mcpServers": {
    "affine": {
      "command": "affine-mcp"
    }
  }
}

Codex CLI：

codex mcp add affine -- affine-mcp

更多特定于客户端的设置在 docs/client-setup.md.

5.验证连接

affine-mcp status
affine-mcp doctor

如果您想通过HTTP而不是stdio远程公开服务器，请从以下步骤开始 docs/配置和部署.md.

兼容性矩阵

刀具表面

tool-manifest.json 是规范工具名称的真实来源。MCP服务器通过以下方式公开这些工具 tools/list 和 tools/call.

域名：

• 工作空间：创建、检查、更新、删除和遍历工作空间
• 组织：集合、集合规则同步、工作区蓝图和实验组织或文件夹帮助程序
• 文档：搜索、读取、创建、发布、移动、标记、导入/导出、语义组合、模板检查和本地实例化、能力和保真度报告以及块级变异
• 数据库：创建列、添加行、更新行、检查模式以及根据意图组合数据库结构
• 注释：列出、创建、更新、删除和解决
• 历史记录：版本历史记录列表
• 用户和令牌：当前用户、登录、个人资料/设置、个人访问令牌
• 通知：列出通知并将其标记为已读
• Blob存储：上传、删除和清理Blob

使用 AFFINE_TOOL_PROFILE=read_only, core，或 authoring 当部署应该暴露比完整部署更小的表面时 full 违约。您还可以将配置文件与 AFFINE_DISABLED_GROUPS 例如 docs.database, destructive，或 admin 以实现更精细的控制。

有关分组目录、注释和操作注意事项，请参见 docs/tool-reference.md.

文档地图

验证您的设置

有用的CLI命令：

• affine-mcp status -测试有效配置
• affine-mcp status --json -机器可读状态输出
• affine-mcp doctor -诊断配置和连接问题
• affine-mcp show-config -打印已编辑机密的有效配置
• affine-mcp config-path -打印配置文件路径
• affine-mcp snippet [--env] -生成可粘贴的客户端配置
• affine-mcp logout -删除存储的凭据

有关常见故障，请参阅：

• docs/gettingstarted.md#常见的首次运行失败
• docs/配置和部署.md#部署检查表

安全和范围

• 永远不要承诺秘密或长期代币
• 在生产过程中，首选API令牌而不是cookie或密码
• 使用HTTPS进行非本地部署
• 定期轮换访问令牌
• 限制暴露的工具 AFFINE_DISABLED_GROUPS 和 AFFINE_DISABLED_TOOLS 用于最低权限设置
• 使用 /healthz 和 /readyz 在容器平台或负载均衡器后面运行HTTP服务器时

发展

在打开PR之前，运行主要质量门：

npm run build
npm run test:tool-manifest
npm run pack:check

附加验证：

• npm run test:comprehensive 启动本地Docker AFFiNE堆栈并验证工具界面
• npm run test:e2e 同时运行Docker、MCP和Playwright
• npm run test:playwright 只运行剧作家套件
• 新型高级刀具表面的聚焦流道包括 npm run test:create-placement, npm run test:capabilities-fidelity, npm run test:native-template, node tests/test-database-intent.mjs, node tests/test-semantic-page-composer.mjs, node tests/test-structured-receipts.mjs, node tests/test-organize-tools.mjs，以及 node tests/test-supporting-tools.mjs

本地克隆流：

git clone https://github.com/dawncr0w/affine-mcp-server.git
cd affine-mcp-server
npm install
npm run build
node dist/index.js

发布说明

• 更改日志.md
• 发布_拒绝.md

许可证

MIT许可证-请参阅 许可证.

支持

• 打开一个问题
• 查看AFFiNE产品文档，网址为 docs.affine.pro

致谢

• 为 AFFiNE 知识库平台
• 使用 模型上下文协议 规格
• 由...驱动 @模型上下文协议/sdk