星战科技xingzhan.cloud
返回市场
仿射-MCP服务器

仿射-MCP服务器

作者：DAWNCR0W35 星标更新：2025-11-05
安装使用来源：spider==github.com

项目介绍

AFFiNE MCP 服务器

一个与AFFiNE（自托管或云）集成的模型上下文协议（MCP）服务器。它通过标准输入输出（stdio）将AFFiNE工作区和文档暴露给AI助手。

版本 MCP SDK 许可证

<a href="https://glama.ai/mcp/servers/@DAWNCR0W/affine-mcp-server"> <img width="380" height="200" src="https://gips0.baidu.com/it/u=1421345468,4172598532&fm=3081&app=3081&f=PNG?w=760&h=400" alt="AFFiNE Server MCP 服务器" /> </a>

概述

  • 目的：通过MCP管理AFFiNE工作区和文档
  • 传输方式：仅支持stdio（兼容Claude Desktop / Codex）
  • 认证方式：Token、Cookie或Email/Password（优先级顺序）
  • 工具：30多种工具加上基于WebSocket的文档编辑
  • 状态：生产就绪（v1.2.1）

新增于v1.2.2：修复CLI二进制文件以始终通过Node运行（无shell误执行）。默认情况下，启动时对email/password登录不阻塞；设置AFFINE_LOGIN_AT_START=sync以在启动时阻塞。

功能

  • 工作区：创建（带初始文档）、读取、更新、删除
  • 文档：列出/获取/搜索/发布/撤销 + 创建/追加段落/删除（基于WebSocket）——新增于v1.2.0
  • 评论：完整的CRUD操作和解决
  • 版本历史：列出和恢复
  • 用户及令牌：个人资料/设置和个人访问令牌
  • 通知：列出和标记为已读

要求

  • Node.js 18+
  • 一个AFFiNE实例（自托管或云）
  • 有效的AFFiNE凭证或访问令牌

安装

# 全局安装（推荐）
npm i -g affine-mcp-server

# 或通过npx临时运行（无需安装）
npx -y -p affine-mcp-server affine-mcp -- --version

该包安装了一个名为affine-mcp的CLI，用于通过stdio运行MCP服务器。

注意：从v1.2.2起，CLI包装器（bin/affine-mcp）确保Node运行ESM入口点，防止shell误解释JS。

配置

通过环境变量进行配置（shell或应用配置）。不再推荐使用.env文件。

  • 必需：AFFINE_BASE_URL
  • 认证（选择一种）：AFFINE_API_TOKEN | AFFINE_COOKIE | AFFINE_EMAIL + AFFINE_PASSWORD
  • 可选：AFFINE_GRAPHQL_PATH（默认/graphql），AFFINE_WORKSPACE_ID，AFFINE_LOGIN_AT_START（默认async，设置为sync以阻塞）

认证优先级：

  1. AFFINE_API_TOKEN → 2) AFFINE_COOKIE → 3) AFFINE_EMAIL + AFFINE_PASSWORD

快速开始

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": "affine-mcp",
      "env": {
        "AFFINE_BASE_URL": "https://your-affine-instance.com",
        "AFFINE_EMAIL": "you@example.com",
        "AFFINE_PASSWORD": "secret!",
        "AFFINE_LOGIN_AT_START": "async"
      }
    }
  }
}

提示：

  • 推荐使用AFFINE_COOKIE或AFFINE_API_TOKEN实现零延迟启动。
  • 如果密码包含!（zsh历史扩展），在shell中将其用单引号包裹或使用上述JSON配置。

Codex CLI

注册MCP服务器到Codex：

  • 全局安装路径（最快）

    • npm i -g affine-mcp-server
    • codex mcp add affine --env AFFINE_BASE_URL=https://your-affine-instance.com --env 'AFFINE_EMAIL=you@example.com' --env 'AFFINE_PASSWORD=secret!' --env AFFINE_LOGIN_AT_START=async -- affine-mcp

  • 使用npx（无需全局安装）

    • codex mcp add affine --env AFFINE_BASE_URL=https://your-affine-instance.com --env 'AFFINE_EMAIL=you@example.com' --env 'AFFINE_PASSWORD=secret!' --env AFFINE_LOGIN_AT_START=async -- npx -y -p affine-mcp-server affine-mcp

  • 令牌或cookie（无需启动时登录）

    • 令牌：codex mcp add affine --env AFFINE_BASE_URL=https://... --env AFFINE_API_TOKEN=... -- affine-mcp
    • Cookie：codex mcp add affine --env AFFINE_BASE_URL=https://... --env "AFFINE_COOKIE=affine_session=...; affine_csrf=..." -- affine-mcp

注意事项：

  • MCP名称：affine
  • 命令：affine-mcp
  • 环境：AFFINE_BASE_URL + 一种认证方法（AFFINE_API_TOKEN | AFFINE_COOKIE | AFFINE_EMAIL/AFFINE_PASSWORD）

可用工具

工作区

  • list_workspaces – 列出所有工作区
  • get_workspace – 获取工作区详情
  • create_workspace – 创建工作区并带有初始文档
  • update_workspace – 更新工作区设置
  • delete_workspace – 永久删除工作区

文档

  • list_docs – 分页列出文档
  • get_doc – 获取文档元数据
  • search_docs – 关键词搜索文档
  • recent_docs – 列出最近更新的文档
  • publish_doc – 将文档设为公开
  • revoke_doc – 撤销公开访问
  • create_doc – 创建新文档（基于WebSocket）
  • append_paragraph – 追加段落块（基于WebSocket）
  • delete_doc – 删除文档（基于WebSocket）

评论

  • list_comments, create_comment, update_comment, delete_comment, resolve_comment

版本历史

  • list_histories, recover_doc

用户及令牌

  • current_user, sign_in, update_profile, update_settings
  • list_access_tokens, generate_access_token, revoke_access_token

通知

  • list_notifications, read_notification, read_all_notifications

Blob存储

  • upload_blob, delete_blob, cleanup_blobs

高级

  • apply_doc_updates – 应用CRDT更新到文档

本地使用（克隆）

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

# 或作为全局CLI暴露给Codex/Claude而不发布
npm link
# 现在像全局二进制一样使用`affine-mcp`

故障排除

认证

  • Email/Password：确保实例允许密码认证且凭证有效
  • Cookie：登录后从浏览器DevTools复制cookies（如affine_session，affine_csrf）
  • Token：生成个人访问令牌；验证其未过期
  • 启动超时：v1.2.2包括CLI包装器修复，默认异步登录以避免阻塞MCP握手。仅在需要时设置AFFINE_LOGIN_AT_START=sync。

连接

  • 确认AFFINE_BASE_URL可达
  • 默认GraphQL端点是/graphql
  • 检查防火墙/代理规则；如果自托管，请验证CORS

安全考虑

  • 不要提交包含机密信息的.env文件
  • 生产环境中优选使用环境变量
  • 定期轮换访问令牌
  • 使用HTTPS
  • 将凭证存储在密钥管理器中

版本历史

1.2.2 (2025-09-18)

  • 添加CLI包装器以确保Node运行ESM入口（bin/affine-mcp），防止shell误执行
  • 清理文档：通过shell/app配置使用环境变量；不再推荐使用.env文件
  • MCP启动行为与1.2.1相同（默认异步登录）

1.2.1 (2025-09-17)

  • 在MCP stdio握手后默认异步email/password登录
  • 新增AFFINE_LOGIN_AT_START环境变量（默认async，设置为sync以在启动时阻塞）
  • 扩展Codex/Claude使用npm、npx和本地克隆的文档

1.2.0 (2025-09-16)

  • 基于WebSocket的文档工具：create_doc，append_paragraph，delete_doc（现在支持创建/编辑/删除）
  • 工具别名：同时支持affine_*和非前缀名称
  • ESM解析：NodeNext；改进构建稳定性
  • CLI二进制文件：affine-mcp便于npm i -g使用

1.1.0 (2025-08-12)

  • 修复带有初始文档的工作区创建（UI可访问）
  • 30多种工具，简化工具名称
  • 改进错误处理和认证

1.0.0 (2025-08-12)

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

贡献

欢迎贡献！

  1. 分叉仓库
  2. 创建特性分支
  3. 为新功能添加测试
  4. 确保所有测试通过
  5. 提交Pull Request

许可证

MIT许可证 - 查看LICENSE文件了解详情

支持

对于问题和疑问：

作者

dawncr0w - GitHub

致谢