1. 从「灵感一闪」到「笔记落地」Flomo MCP Server 到底解决什么问题你有没有过这种时刻正在 Claude Desktop 里跟 AI 聊一个技术方案聊到一半突然冒出一个想法想立刻存进 Flomo结果只能手动切窗口、复制、粘贴、再切回来。一次两次还行次数多了思路就断了。Flomo MCP Server 就是冲着这个断点来的。它是一个基于 TypeScript 实现的 MCPModel Context Protocol服务器核心只做一件事把write_note这个工具暴露给支持 MCP 的客户端让 AI 助手能直接往你的 Flomo 里写笔记。你不用离开对话窗口不用手动复制AI 说「已记录」笔记就已经躺在 Flomo 里了。MCP 是什么你可以把它理解成 AI 客户端的「USB 接口」。以前每个 AI 工具想接外部服务都得自己写一套适配MCP 把这个适配标准化了——只要服务端按 MCP 协议暴露工具任何支持 MCP 的客户端都能调用。Flomo MCP Server 就是这样一个标准化的「Flomo 写入适配器」。它适合谁三类人最明显一是重度 Flomo 用户笔记流就是第二大脑任何能自动往里灌内容的方式都值得试二是用 Claude Desktop、Cline、Cursor 这类支持 MCP 的客户端做日常开发的工程师想把「记录」这个动作嵌进工作流三是想拿它当 MCP 入门练手项目的人因为它的工具只有一个write_note参数只有一个content结构足够简单跑通一遍就能理解 MCP 的配置、鉴权、调用、验证全链路。这篇文章不讲空概念直接给你可复制的配置片段、可执行的调用示例以及写入之后怎么确认笔记真的进去了。TypeScript 实现的服务Node.js 环境跑起来全程本地不涉及任何网络中转。2. 前置准备Flomo API URL 获取与 MCP 客户端环境确认在写配置之前有两样东西必须先到位Flomo 的 API URL以及一个能跑 MCP 的客户端。这两样缺一个后面的write_note都调不通。2.1 Flomo API URL 怎么拿Flomo 给每个账号提供了一个专属的写入 API URL格式类似https://flomoapp.com/iwh/xxxxxx/xxxxxx/。获取路径是登录 Flomo 网页版进入「设置」→「API」→「获取 API URL」复制那一整串。这个 URL 本身就是凭证谁拿到谁就能往你的 Flomo 写东西所以别贴到公开仓库里。拿到之后先别急着配 MCP用 curl 单独验一下这个 URL 是活的curl -X POST https://flomoapp.com/iwh/你的专属路径/ \ -H Content-Type: application/json \ -d {content: API URL 连通性测试}返回{code:0}之类的成功结构说明 URL 有效。如果返回 404 或 403大概率是复制时漏了尾部斜杠或者 URL 已经失效需要重新生成。这一步单独做是为了把「URL 问题」和「MCP 配置问题」隔离开——后面排障时你会感谢这个习惯。2.2 MCP 客户端环境确认Flomo MCP Server 本身是个 npm 包通过npx拉起所以本机需要 Node.js 16 以上。先确认版本node -v npm -vNode 低于 16 的话npx -y mcp-so/mcp-server-flomo可能因为语法或依赖问题直接报错。升级到 LTS 版本最稳。客户端这边Claude Desktop 是最常见的载体它的 MCP 配置文件位置分平台macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.json如果你用的是 Cline、Cursor 或别的支持 MCP 的编辑器配置文件路径不同但结构一致都是往mcpServers里加一个条目。下面统一用 Claude Desktop 的路径举例你按自己客户端替换即可。2.3 关于 TaoToken 的接入位置这里要说明一下 TaoToken 在整条链路里的角色。Flomo MCP Server 负责「写笔记」但它不负责「跟模型对话」。如果你希望 AI 在对话中自动判断「这句话值得记」然后调用write_note那对话这一侧需要一个模型服务。TaoToken 提供的就是这一侧的 API 接入能力Base URL 是https://taotoken.net/api你可以在支持自定义 Base URL 的客户端里把模型请求指向它再配合 MCP 工具调用形成「对话 → 判断 → 写笔记」的闭环。需要区分清楚Flomo 的 API URL 是写给 Flomo 的TaoToken 的 Key 是写给模型服务的两者不是一回事配置时别混在同一个 env 里。MCP Server Flomo 的env里只放FLOMO_API_URL模型侧的 Key 放在客户端自己的模型配置里。3. 可复制配置mcpServers 片段与 write_note 工具声明这一节是全文最核心的部分配置写对了后面基本就是顺水推舟。3.1 最小可用配置片段打开你的 MCP 客户端配置文件在mcpServers对象里加入flomo条目。完整片段如下直接复制后把FLOMO_API_URL换成你自己的{ mcpServers: { flomo: { command: npx, args: [ -y, mcp-so/mcp-server-flomo ], env: { FLOMO_API_URL: https://flomoapp.com/iwh/你的专属路径/ } } } }逐字段说明一下避免你改错字段作用常见错误command启动命令这里是npx写成node会找不到包args传给命令的参数-y表示自动确认安装漏掉-y会卡在交互确认env.FLOMO_API_URLFlomo 写入凭证漏尾部斜杠、复制了多余空格-y这个参数很关键。npx第一次拉取mcp-so/mcp-server-flomo时会问「是否安装」而 MCP 客户端启动服务时是非交互的没有-y就会一直卡住表现为客户端里这个 server 一直显示 connecting 但永远不 ready。3.2 如果你用 TOML 配置Codex 类客户端部分客户端用 TOML 而不是 JSON比如 Codex 的config.toml。等价写法[mcp_servers.flomo] command npx args [-y, mcp-so/mcp-server-flomo] [mcp_servers.flomo.env] FLOMO_API_URL https://flomoapp.com/iwh/你的专属路径/注意 TOML 里字符串用双引号数组用方括号层级用点号或分段表头别把 JSON 的花括号带进来。3.3 write_note 工具声明服务启动后MCP 客户端会通过协议向服务端拉取工具列表。Flomo MCP Server 暴露的工具就一个{ name: write_note, description: 向 Flomo 写入一条文本笔记, inputSchema: { type: object, properties: { content: { type: string, description: 笔记内容文本 } }, required: [content] } }content是唯一必填参数类型 string。这意味着调用时你只需要给一段文本服务端负责把它 POST 到你的 Flomo API URL。没有标题、没有标签、没有分类参数——想加标签的话直接在content里写#标签Flomo 自己会解析。3.4 三件套对照Base URL、Key、Model ID如果你同时接了模型侧比如通过 TaoToken 接入 Claude 或 GPT 系列配置里会出现三件套这里明确一下各自归属避免串台Base URL模型侧填https://taotoken.net/api这是模型请求的入口不是 Flomo 的。Key模型侧的 API Key在 TaoToken 控制台的 API Keys 页面生成填在客户端的模型配置里。Model ID你选用的具体模型标识填在客户端模型选择处。而 Flomo 侧只有FLOMO_API_URL一个凭证它跟上面三件套不在同一层。很多人第一次配会把 Flomo 的 URL 填到模型的 Base URL 里结果模型请求 404Flomo 也写不进去两边都报错。记住MCP 的env只管 MCP 服务自己的依赖模型配置在客户端另一处。4. 验证请求从工具调用到笔记落地的完整链路配置写完重启客户端接下来要确认三件事服务起来了、工具能调、笔记真进去了。4.1 确认服务已加载重启 Claude Desktop 后看输入框附近有没有出现工具图标或者进设置里的 MCP 面板应该能看到flomo这个 server 状态是 connected。如果显示 failed 或一直 connecting先别往下走去第 5 节排障。也可以用 MCP Inspector 单独验服务不依赖客户端npx modelcontextprotocol/inspector npx -y mcp-so/mcp-server-flomoInspector 会起一个本地网页你在里面能看到write_note工具手动填content点调用直接看返回。这一步能把「服务本身有没有问题」和「客户端配置有没有问题」分开。4.2 发起一次 write_note 调用在 Claude Desktop 对话框里直接说帮我把这句话记到 FlomoMCP 的 write_note 工具调用测试成功AI 会识别到有write_note可用发起工具调用。底层发出的请求结构大致是{ tool: write_note, arguments: { content: MCP 的 write_note 工具调用测试成功 } }服务端收到后把它转成对 Flomo API 的 POSTcurl -X POST https://flomoapp.com/iwh/你的专属路径/ \ -H Content-Type: application/json \ -d {content: MCP 的 write_note 工具调用测试成功}Flomo 返回成功结构服务端再把结果回传给客户端你在对话里会看到「已写入」之类的确认。4.3 验证笔记真的进去了别只看 AI 说「成功」就完事去 Flomo 里确认。打开 Flomo 网页版或 App刷新最新一条应该就是你刚写的内容。如果对话显示成功但 Flomo 里没有大概率是FLOMO_API_URL指向了错误的账号或者 URL 已失效但返回了非标准成功码。更严谨的验证方式是看服务端返回的原始响应。在 Inspector 里调用时返回体会包含 Flomo 的响应 JSONcode为 0 通常表示成功。如果返回里有message字段描述错误按那个信息排查。4.4 批量与自动化场景验证单条通了之后可以试连续写入确认服务稳定{tool: write_note, arguments: {content: 第一条 #测试}} {tool: write_note, arguments: {content: 第二条 #测试}} {tool: write_note, arguments: {content: 第三条 #测试}}三条都进 Flomo且标签#测试被正确解析说明链路完全打通。这时候你就可以把它接进更复杂的自动化流程比如让 AI 在代码 review 后自动把结论写进 Flomo或者把每天的对话摘要归档。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth这一节按真实报错来遇到哪个查哪个。5.1 401 Unauthorized最常见。write_note调用返回 401说明 Flomo 侧拒绝了请求。原因通常是FLOMO_API_URL不对复制时漏了尾部斜杠、多了空格、或者 URL 已经重新生成过导致旧的失效。解决方式是回 Flomo 设置里重新复制一次粘贴时注意别带首尾空白。用 2.1 节的 curl 单独验curl 通了 MCP 才可能通。5.2 local proxy failed这个报错通常出现在客户端启动 MCP 服务时提示本地代理失败。它跟 Flomo 无关是客户端拉取npx包的过程出了问题。可能原因Node 版本过低、npm 源不可达、或者npx缓存损坏。先清缓存再试npm cache clean --force npx -y mcp-so/mcp-server-flomo --help如果--help能正常输出说明包本身没问题那就是客户端配置里的command或args写错了。检查是不是把npx写成了绝对路径但路径不对或者args数组里漏了-y。5.3 reading choices 相关报错这类报错一般出现在模型侧返回结构解析时提示读取choices字段失败。它跟 Flomo MCP 没有直接关系而是模型 API 的响应格式不符合客户端预期。如果你是通过自定义 Base URL 接入模型确认 Base URL 填的是https://taotoken.net/api且 Model ID 是服务端支持的标识。Base URL 多写或少写路径段都会导致返回结构不是标准的choices数组客户端解析就炸。5.4 OAuth 相关报错Flomo MCP Server 用的是 API URL 凭证不走 OAuth。如果你看到 OAuth 报错说明报错来自模型侧或客户端自身的登录流程不是 Flomo MCP。检查客户端的账号登录状态以及模型侧 Key 是否有效。Key 失效会在模型请求阶段报 401跟 Flomo 的 401 长得像但来源不同——看报错里提到的域名就能区分。5.5 工具列表里没有 write_note服务 connected 但工具列表空通常是服务启动后拉取工具失败。用 Inspector 单独跑一次看工具能不能列出来。Inspector 能列出而客户端列不出就是客户端版本对 MCP 协议支持的问题升级客户端。Inspector 也列不出就是包本身的问题确认mcp-so/mcp-server-flomo版本必要时指定版本号安装。6. 把 Flomo 接进你的 AI 工作流下一步怎么走配置跑通只是起点。真正让这套东西产生价值的是把它嵌进你每天已经在用的流程里。一个我常用的做法在 Claude Desktop 里做技术方案讨论时约定一个暗号比如我说「记一下」AI 就把当前结论通过write_note写进 Flomo并自动带上#方案标签。这样一场对话下来Flomo 里自动沉淀出结构化的要点不用我事后回忆整理。如果你想让模型侧也走统一入口可以在客户端里把模型请求指向 TaoToken 的 APIBase URL 用https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。这样对话和工具调用在同一套配置里管理排查问题时链路更清晰。需要看接入细节的话接入文档里有各客户端的配置示例。对于长期做编码和 Agent 场景的人如果每天都要反复调模型、跑工具链可以了解一下 Coding Plan它更适合高频、持续的开发使用比单次按量更省心。而如果你只是想先验证某个模型在write_note这类工具调用上的表现直接去模型对话页面试几条比本地配半天更快得到结论。最后提醒一句FLOMO_API_URL等同于你 Flomo 的写入密码别提交到 Git别贴在公开 issue 里。本地配置文件如果会同步到云端确认同步范围可控。笔记流是你的第二大脑入口凭证值得当密码一样对待。