1. 项目概述当开源笔记工具遇上AI智能体最近在折腾AI智能体Agent的本地化部署和功能扩展发现了一个挺有意思的项目DAWNCR0W/affine-mcp-server。简单来说这是一个为开源笔记应用Affine打造的MCPModel Context Protocol服务器。如果你对Affine不熟悉可以把它理解为一个集成了Notion式块编辑、白板协作和本地优先特性的新一代知识管理工具。而MCP则是Anthropic提出的一套协议旨在让大语言模型LLM能够安全、标准化地访问外部工具、数据和功能。你可以把它看作是连接AI大脑如Claude、GPT与外部世界你的文件、数据库、应用的一座“标准化桥梁”。那么这个项目具体是做什么的它本质上是一个“翻译器”和“连接器”。它把你在Affine笔记里存储的知识——那些页面、数据库、待办事项——通过MCP协议暴露出来。这样一来当你与支持MCP的AI助手比如在Claude Desktop里对话时你就可以直接说“帮我查一下上个月项目会议纪要里提到的技术难点”或者“把我‘学习计划’数据库里所有未完成的任务列出来”。AI助手通过这个MCP服务器就能直接读取、搜索甚至修改你的Affine工作区内容而无需你手动复制粘贴或切换应用。这解决了什么痛点对于深度使用笔记工具进行知识管理、项目规划和内容创作的人来说最大的困扰之一就是信息孤岛。想法、记录、资料都在笔记里但当你需要AI协助分析、总结或基于这些内容创作时却不得不进行繁琐的导出或摘要描述。affine-mcp-server直接打通了这条管道让AI能“看见”并“理解”你的知识库上下文实现真正基于你个人或团队知识资产的智能交互。它特别适合开发者、研究者、内容创作者以及任何希望将个人知识库与AI能力深度结合的用户。2. 核心架构与工作原理拆解要理解这个项目怎么用甚至想自己二次开发得先摸清它的底子。整个项目的架构可以分成三层协议层MCP、适配层Server、数据源层Affine。2.1 MCP协议层AI与工具对话的“世界语”MCP不是一个具体的软件而是一套规范。你可以把它想象成USB协议。不同的设备U盘、键盘、手机只要遵循USB协议就能接入电脑进行通信。MCP同理它定义了一套标准化的方式让AI模型客户端能够发现、调用远程服务器提供的各种“工具”Tools和“资源”Resources。在这个项目里affine-mcp-server就是一个实现了MCP协议的服务器。它向AI客户端宣告“我这里提供了以下几个工具search_affine_pages搜索页面、get_affine_page_content获取页面内容、query_affine_database查询数据库等等。” 同时它也把Affine工作区里的页面、数据库条目等以“资源”的形式暴露出来AI可以直接引用这些资源的URI统一资源标识符。协议通信通常基于JSON-RPC over stdio标准输入输出或HTTP传输的信息结构化程度很高确保了交互的精确性和安全性。服务器不需要知道对面是Claude还是GPT客户端也不需要知道背后是Affine还是别的什么笔记大家只要都说“MCP”这门语言就能协作。2.2 服务器适配层从协议到Affine API的转换这是本项目的核心代码所在。它的主要任务是把通用的MCP请求“翻译”成针对Affine的具体操作。Affine本身提供了云端和本地的API。这个MCP服务器需要处理身份认证比如获取和使用API Token、构造符合Affine API规范的HTTP请求、处理响应以及错误。例如当AI客户端通过MCP调用search_affine_pages工具并传入参数query: 季度复盘时服务器层需要验证当前会话的权限。将请求转换为向 Affine 服务器发送的POST /api/search/workspaces/{workspace_id}/pages请求。接收Affine返回的JSON数据可能是一个页面列表。再将这个列表格式化为MCP协议规定的工具调用结果格式返回给AI客户端。这一层还负责实现MCP的“资源”模型。例如它可以将一个Affine页面的URLhttps://app.affine.pro/workspace/xxx/page/yyy声明为一个MCP资源并为其提供一个read操作。当AI在对话中引用这个资源URI时MCP服务器就能直接获取其最新内容。2.3 数据源层Affine工作区与数据模型这是信息的源头。Affine的数据模型基于“块”Block页面由各种块文本、标题、列表、数据库、白板元素等组成。此外Affine强大的数据库功能可以看作是一个内嵌的、结构化的表格。MCP服务器需要理解这些数据模型才能进行有效的搜索和内容提取。例如搜索时可能需要同时匹配页面标题和块内容获取页面内容时需要将嵌套的块结构扁平化为连贯的文本以便AI处理查询数据库时需要理解列属性和行条目的关系。一个核心的考量是数据同步模式Affine有“本地优先”的特性数据首先存储在本地IndexedDB然后同步到云端。MCP服务器目前主要通过云端API操作这意味着它操作的是已同步到云端的、相对较新的数据快照。对于纯本地、未同步的数据目前的架构可能无法访问这是设计上的一个边界也需要在使用时注意。3. 环境准备与部署实操指南理论清楚了我们来看看怎么把它跑起来。部署affine-mcp-server主要有两种方式本地运行开发/测试和通过MCP客户端集成生产使用。这里我们以最常用的、与Claude Desktop集成为例详细走一遍流程。3.1 前置条件与依赖安装首先你需要准备好以下几样东西Node.js环境该项目基于Node.js建议安装LTS版本如18.x或20.x。你可以从Node.js官网下载安装包或者使用nvmNode Version Manager进行多版本管理。Affine账户与工作区你需要一个Affine账户免费版即可并创建一个工作区里面有一些测试用的页面和数据库。这是服务器将要连接的数据源。Affine API Token这是服务器访问你数据的“钥匙”。登录 Affine 网页版 (app.affine.pro)。点击左下角个人头像进入「Settings」。找到「Developer」或「API」选项具体位置可能随版本更新变动通常在设置高级选项里。生成一个新的API Token并立即复制保存好。这个Token只会显示一次丢失后需要重新生成。Claude Desktop应用这是我们将要配置的MCP客户端。从Anthropic官网下载并安装。3.2 服务器本地运行与配置接下来我们获取并运行MCP服务器。# 1. 克隆项目代码假设你有Git环境 git clone https://github.com/DAWNCR0W/affine-mcp-server.git cd affine-mcp-server # 2. 安装项目依赖 npm install # 3. 准备环境变量配置文件 # 项目根目录下通常需要一个 .env 文件来配置敏感信息 # 复制提供的示例配置文件如果存在 cp .env.example .env # 4. 编辑 .env 文件填入你的Affine凭证 # 使用你喜欢的文本编辑器如 VS Code, nano, vim code .env在.env文件中你需要配置至少以下关键信息AFFINE_API_TOKEN你的Affine_API_Token_粘贴在这里 AFFINE_WORKSPACE_ID你的目标工作区ID如何获取WORKSPACE_ID打开你的Affine网页版进入你想要连接的工作区。浏览器地址栏的URL格式通常为https://app.affine.pro/workspace/[WORKSPACE_ID]/...。中间的那串字符就是你的工作区ID。# 5. 启动MCP服务器开发模式 npm run dev如果一切正常终端会输出服务器启动日志并等待标准输入stdio的连接。这表明你的MCP服务器已经在本地运行起来了它正在监听来自MCP客户端的指令。注意首次运行如果遇到依赖包编译错误特别是涉及本地二进制模块的可以尝试删除node_modules和package-lock.json然后用npm install --force重新安装。确保你的Node.js版本符合项目要求查看package.json中的engines字段。3.3 集成到Claude Desktop让Claude Desktop认识并使用我们这个本地服务器是关键一步。找到Claude Desktop的配置目录macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json编辑配置文件如果文件不存在就创建一个。我们需要在其中添加MCP服务器的配置。{ mcpServers: { affine: { command: node, args: [ /绝对路径/到/你的/affine-mcp-server/build/index.js ], env: { AFFINE_API_TOKEN: 你的Affine_API_Token, AFFINE_WORKSPACE_ID: 你的Affine_Workspace_ID } } } }重要参数解释command: node指定用Node.js运行时来执行我们的服务器脚本。args数组里的第一个元素必须是服务器入口文件的绝对路径。如果你是用npm run dev开发入口可能是src/index.ts如果是生产构建后则是build/index.js。请根据你的实际情况修改。env这里直接传递环境变量。这是一种方式但将敏感Token直接写在配置文件中存在安全风险特别是如果配置文件可能被同步或备份时。更安全的方式是让服务器从本地.env文件读取而配置文件中只保留非敏感参数或指向一个启动脚本。更安全的配置实践推荐 创建一个启动脚本例如start_server.sh或start_server.bat在脚本中设置环境变量或加载.env文件然后在Claude配置中指向这个脚本。macOS/Linux (start_server.sh):#!/bin/bash cd /绝对路径/到/你的/affine-mcp-server # 使用 dotenv 或其他方式加载环境变量 export AFFINE_API_TOKEN你的Token export AFFINE_WORKSPACE_ID你的WorkspaceID exec node ./build/index.js记得给脚本执行权限chmod x start_server.sh。 然后在claude_desktop_config.json中{ mcpServers: { affine: { command: /绝对路径/到/你的/affine-mcp-server/start_server.sh } } }Windows (start_server.bat):echo off cd C:\绝对路径\到\你的\affine-mcp-server set AFFINE_API_TOKEN你的Token set AFFINE_WORKSPACE_ID你的WorkspaceID node .\build\index.js配置中command指向此.bat文件。重启Claude Desktop保存配置文件后完全退出并重新启动Claude Desktop应用。启动时Claude会读取配置尝试启动你定义的MCP服务器。你可以在Claude Desktop的日志中查看连接状态通常通过菜单栏的“Help” - “View Logs”可以找到。4. 核心功能使用与场景演示服务器成功连接后你就可以在Claude的对话窗口中体验它带来的能力了。Claude会自动识别服务器提供的工具并在合适的时机建议或直接使用它们。下面我们通过几个典型场景来演示。4.1 场景一基于个人知识库的智能问答这是最直接的应用。假设你的Affine里有一个名为“产品需求文档”的页面里面详细记录了某个功能的需求描述、用户故事和验收标准。你的提问“我那个‘产品需求文档’的页面里关于‘用户登录’这个功能提到的性能要求是什么”Claude的处理流程理解意图Claude识别出你需要查询特定页面“产品需求文档”中的特定信息“用户登录的性能要求”。调用工具Claude会优先使用search_affine_pages工具搜索标题或内容包含“产品需求文档”的页面找到对应的页面ID。获取内容然后Claude使用get_affine_page_content工具传入上一步得到的页面ID获取该页面的完整文本内容。分析与回答Claude在本地对话上下文中分析获取到的页面文本定位到“用户登录”相关段落提取出“性能要求”部分例如“登录接口响应时间应小于200ms支持每秒1000次并发登录请求。”并组织成自然语言回复给你。整个过程几乎是瞬间完成的你无需手动打开Affine、查找页面、复制文本。AI直接在你的知识库中完成了信息检索和提取。4.2 场景二数据库的查询、分析与汇总Affine的数据库功能强大你可以用它管理任务、客户信息、阅读清单等。MCP服务器的query_affine_database工具让AI能直接与这些数据库交互。你的提问“帮我看看‘项目任务看板’这个数据库里所有状态是‘进行中’且负责人是‘小王’的任务把它们的标题和截止日期列出来。”Claude的处理流程解析查询Claude理解你需要查询一个名为“项目任务看板”的数据库并带有过滤条件状态“进行中” 负责人“小王”和投影字段标题、截止日期。调用工具Claude使用query_affine_database工具。它需要知道数据库的ID。它可能会先通过search_affine_pages或list_affine_resources找到这个数据库页面获取其ID。执行查询服务器将查询转换为对Affine数据库API的调用执行过滤和排序。格式化结果服务器将查询结果一个JSON数组每条记录包含标题、截止日期等属性返回给Claude。Claude将其格式化为一个清晰的表格或列表呈现在回复中。更进一步你可以让AI进行分析“基于这个列表告诉我有哪些任务本周截止”或者“计算一下小王平均每个任务的处理时长是多少”。AI可以结合数据库查询结果和自身的计算、推理能力给出更深层次的洞察。4.3 场景三内容创作与知识整合你正在撰写一篇关于“Web3.0发展趋势”的博客你的Affine里散落着很多相关的阅读笔记、会议记录和灵感碎片。你的指令“我想写一篇关于Web3.0发展趋势的文章。请搜索我Affine工作区里所有和‘Web3’、‘区块链’、‘去中心化’相关的页面和笔记提取其中的核心观点、案例和数据并为我生成一个初步的文章大纲。”Claude的处理流程广泛搜索Claude会多次调用search_affine_pages工具或利用其分页能力使用你提供的关键词进行多轮搜索尽可能收集相关材料。内容获取与摘要对于搜索到的关键页面Claude会获取其内容并利用其强大的文本理解能力为每个页面或段落生成摘要识别核心观点、数据和引用来源。综合与大纲生成基于所有提取的信息Claude进行交叉分析、去重和归类识别出几个主要的发展趋势如DeFi、NFT、DAO、Layer2等。然后它为你的文章构思一个逻辑清晰的大纲每个部分可能包含主题句、来自你笔记的支撑论据、可用的数据案例以及需要进一步补充研究的方向提示。这极大地提升了从零开始写作或整合碎片化知识的效率。AI不再是凭空想象而是基于你已有的、可信的知识储备进行创作辅助。5. 高级配置、优化与二次开发基础功能用熟了你可能会想让它更贴合自己的需求或者探索一些更高级的玩法。5.1 性能优化与缓存策略频繁搜索和获取页面内容可能会产生较多的API调用尤其是当你的工作区内容很多时。为了提升响应速度和减轻服务器负担可以考虑在MCP服务器层引入缓存。页面内容缓存对于get_affine_page_content工具可以设计一个基于页面ID和最后修改时间的缓存。当请求某个页面时先检查本地缓存是否存在且未过期例如设置5分钟的TTL如果命中则直接返回缓存内容避免网络请求。这需要修改服务器代码在调用Affine API前加入缓存逻辑。搜索索引缓存search_affine_pages的查询结果也可以根据查询关键词进行短期缓存。但要注意搜索结果的实时性要求可能比页面内容更高缓存时间应更短或者在检测到工作区有更新时如果Affine有webhook通知主动清除相关缓存。实现建议可以使用node-cache或lru-cache这类轻量级内存缓存库。在工具处理函数的开头和结尾加入缓存读写逻辑即可。记住缓存是“牺牲一致性换取性能”要根据你的使用场景权衡。5.2 安全性加固实践将个人笔记API Token交给一个本地服务器安全至关重要。Token隔离绝对不要将API Token提交到Git仓库或分享给他人。坚持使用.env文件管理并将.env添加到.gitignore。在Claude Desktop配置中优先使用启动脚本设置环境变量而不是明文写在JSON配置里。权限最小化Affine的API Token目前可能具有对应账户在对应工作区内的全部读写权限。定期在Affine设置中检查并轮换重新生成Token。如果未来Affine支持更细粒度的API权限控制务必遵循最小权限原则只授予必要的权限例如如果MCP服务器只读就申请只读Token。本地网络限制MCP服务器默认通过stdio与客户端通信这是一个本地进程间通信通道相对安全。确保你的服务器没有无意中开放额外的网络端口。如果你修改了代码要避免引入任何可能将数据外泄到远程服务器的风险。审计日志考虑在服务器代码中添加简单的操作日志功能记录哪些工具被调用、传入的参数是什么可脱敏、何时调用。这有助于事后审计和故障排查。日志可以输出到本地文件但要妥善保管日志文件。5.3 功能扩展与二次开发思路开源项目的魅力在于可以按需定制。以下是一些扩展方向增加写操作工具目前项目主要提供读操作搜索、获取、查询。你可以尝试添加create_affine_page、append_to_page、update_database_row等工具。这需要深入研究Affine的写API并谨慎处理并发和冲突问题。从简单的“追加文本到页面末尾”开始是个好主意。支持更多资源类型除了页面和数据库Affine还有白板Whiteboard、标签Tag等。可以为这些资源类型实现MCP的Resource接口让AI也能“看到”白板上的元素关系或标签体系。实现更智能的搜索目前的搜索可能依赖于Affine的基础搜索API。你可以在服务器端集成一个轻量级的本地全文检索引擎如FlexSearch对已获取的页面内容建立索引实现更快速、更灵活的全文检索甚至支持语义搜索结合本地运行的嵌入模型。多工作区支持修改配置允许同时连接多个Affine工作区并通过工具参数指定目标工作区。这需要对现有的身份认证和API调用逻辑进行抽象化。开发图形化配置界面对于非开发者用户可以构建一个简单的Electron或Tauri桌面应用通过图形界面来配置API Token、工作区ID、选择缓存策略等并生成Claude Desktop所需的配置文件降低使用门槛。二次开发时请务必仔细阅读项目的源码结构理解MCP SDK如modelcontextprotocol/sdk的使用方式以及如何定义新的Tools和Resources。良好的开端是从复制一个现有工具的实现开始修改。6. 常见问题与故障排查实录在实际部署和使用过程中你难免会遇到一些问题。这里记录了一些常见坑点和解决方法。6.1 连接与启动失败问题现象可能原因排查步骤与解决方案Claude Desktop启动后侧边栏没有出现Affine工具图标或提示MCP服务器连接错误。1. 配置文件路径或格式错误。2. Node.js路径或服务器入口文件路径错误。3. 环境变量未正确设置。4. 服务器代码本身启动报错。1.检查配置文件确认claude_desktop_config.json文件在正确目录且JSON格式正确无尾随逗号字符串引号匹配。可以使用在线JSON校验工具。2.检查路径确保command和args中的路径是绝对路径并且指向真实存在的文件。在终端中手动执行一下配置中的命令看能否启动服务器。3.查看日志打开Claude Desktop的日志文件Help - View Logs搜索“mcp”、“affine”等关键词通常会有详细的错误信息。4.独立运行服务器在终端中切换到项目目录手动运行node build/index.js或npm run dev查看控制台是否有报错如缺少环境变量、API Token无效、网络错误等。根据错误信息逐一解决。手动运行服务器时提示Cannot find module或语法错误。1. 依赖未安装。2. TypeScript未编译。3. Node.js版本不兼容。1. 运行npm install确保所有依赖已安装。2. 如果项目是TypeScript写的确保执行了构建命令npm run build生成了build/index.js。开发时用npm run dev。3. 检查package.json中的engines字段确保你的Node.js版本符合要求。服务器启动成功但Claude无法调用工具提示权限错误或“工具不可用”。1. Affine API Token无效或过期。2. Workspace ID不正确或无访问权限。3. 服务器代码中API调用逻辑有误。1. 去Affine设置中确认API Token是否有效尝试重新生成一个并更新到环境变量中。2. 再次确认Workspace ID是否来自正确的、你有权限访问的工作区。3. 在服务器代码中添加更详细的日志打印出API请求的URL和响应状态码帮助定位是认证失败还是其他API错误。6.2 工具调用异常与数据问题问题现象可能原因排查步骤与解决方案搜索工具search_affine_pages返回结果为空但你确定有相关页面。1. Affine云端搜索索引延迟。2. 搜索关键词不匹配或过于具体。3. 服务器代码中搜索API的参数传递有误。1. Affine的云端搜索可能不是实时的。尝试在Affine网页版内用相同关键词搜索确认是否能搜到。等待几分钟再试。2. 尝试使用更通用、更可能出现在标题中的关键词。或者让AI尝试用页面ID直接获取内容。3. 检查服务器调用Affine搜索API时是否正确地传递了workspace_id和query参数。get_affine_page_content返回的内容格式混乱或缺失。1. Affine的块Block结构到纯文本的转换不完善。2. 页面包含图片、代码块、数据库等复杂元素转换时被忽略或处理不当。1. 这是当前项目可能存在的局限。查看服务器代码中解析页面内容的函数可能是parsePageContent或类似函数看它是如何遍历和拼接块内容的。你可能需要根据Affine的块类型type字段进行更精细的处理例如为代码块添加标记为图片保留替代文本等。2. 考虑修改代码将内容以更结构化的格式如Markdown返回而不仅仅是纯文本这样AI处理起来可能效果更好。查询数据库query_affine_database时过滤或排序不生效。1. 数据库的属性列名称不匹配。2. 服务器代码中构建查询过滤器Filter或排序Sort的语法错误。1. 让AI先使用工具列出数据库的属性如果工具支持或者你自己在Affine网页版查看数据库的列名。确保在查询时使用的属性名完全一致注意大小写和空格。2. 查阅Affine官方API文档确认过滤器和排序的JSON结构。在服务器代码的数据库查询函数中添加日志打印出最终发送给Affine API的请求体与文档示例进行比对。6.3 性能与稳定性问题工具调用响应慢除了前面提到的引入缓存还可以检查网络。如果Affine的API服务器响应慢会导致所有工具调用延迟。可以尝试在非高峰时段使用。如果服务器部署在国外而你在国内网络延迟可能是一个因素但目前Affine的服务器位置需要具体确认。Claude Desktop偶尔失去连接MCP服务器进程可能意外退出。确保你的启动脚本是稳定的没有内存泄漏。对于生产环境可以考虑使用进程管理工具如PM2来守护MCP服务器进程并在崩溃时自动重启。然后在Claude配置中command指向一个由PM2管理的脚本或直接使用PM2的启动命令。API调用额度限制虽然Affine目前可能没有严格的公开API调用限制但频繁、大量的自动化调用理论上可能触发风控。在二次开发时避免设计会发起极高频率请求的工具。在代码中加入适当的延迟例如工具调用间间隔100-200毫秒和错误重试机制带指数退避。最后一点实操心得MCP生态还在早期affine-mcp-server这类项目是连接AI与个人工具链的宝贵探索。它的价值不在于功能有多复杂而在于它定义并实现了一种标准的、可扩展的交互模式。遇到问题时多查看Claude Desktop的日志和服务器控制台输出大部分错误信息都足够清晰。在修改代码前先确保你完全理解了现有代码的逻辑从一个小的、可验证的修改点开始。这个项目就像给你最喜欢的螺丝刀Affine配了一个电动适配头MCP让更强大的动力源AI能更方便地使用它至于能拧出什么花样就看你的想象力了。