flomo-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@flomo-mcp 在 flomo 里搜一下关于 docker 的笔记"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
flomo-mcp
English | 中文
让 AI 直接读写你的 flomo 笔记——无需任何 API Key。flomo-mcp 是一个 MCP server,通过本机已登录的 flomo 桌面客户端(macOS)向 AI 客户端(Claude Desktop、ZCode、Cursor 等)提供笔记与标签的完整读写能力。
这是什么
flomo 没有公开 API。本项目不做"逆向接口 + 手工签名",而是通过 Chrome DevTools Protocol 连接本机 flomo 桌面客户端,在页面上下文中直接调用应用内部的请求层,token、签名、请求路由全部由 flomo 自己处理:
AI 客户端 ──stdio──▶ flomo-mcp ──CDP(127.0.0.1:9222)──▶ flomo 桌面客户端
│ 在 flomo 页面上下文执行
│ window.__flomoVuexStore._vm.$api.*
▼
https://flomoapp.com/api/v1
(认证/签名由 flomo 自身处理)认证零配置:不存储任何凭证,token 始终留在 flomo 的 localStorage 里,flomo 里重新登录后自动跟随
随版本免维护:API 调用复用页面内 webpack 打包的
$api单例,签名算法、请求头由应用自己生成,flomo 常规更新不破坏兼容兜底拉起:每次工具调用前检查调试口;flomo 未启动会自动带
--remote-debugging-port=9222拉起,已启动但无调试口会自动重启它
能做什么
你对 AI 说 | 背后调用的工具 |
"flomo 里搜一下关于 docker 的笔记" |
|
"看看我最近写了什么" |
|
"帮我把这条想法记到 flomo,带上 #灵感 标签" |
|
"把 xxx 这条笔记改成…" |
|
"我有哪些标签?把『读书』置顶" |
|
"把标签 读书 改成 阅读/读书" |
|
全部 12 个工具(5 只读 / 7 写)的参数与返回结构见 TOOLS.md。
Related MCP server: Memos MCP Server
使用
环境要求
macOS + 已登录的 flomo 桌面客户端(默认路径
/Applications/flomo.app)Node.js ≥ 22.4(依赖原生 WebSocket,无需 puppeteer 等外部浏览器)
安装
已发布到 npm,推荐用 npx 直接运行,无需 clone:
npx @location-txl/flomo-mcp从源码运行(面向开发者):
git clone https://github.com/location-txl/flomo-mcp.git ~/flomo-mcp
cd ~/flomo-mcp
npm install
npm run build注册到 MCP 客户端
{
"mcpServers": {
"flomo": {
"command": "npx",
"args": ["-y", "@location-txl/flomo-mcp"]
}
}
}flomo 不装在默认路径时,通过环境变量指定:
{
"mcpServers": {
"flomo": {
"command": "npx",
"args": ["-y", "@location-txl/flomo-mcp"],
"env": { "FLOMO_APP_PATH": "/你的路径/flomo.app" }
}
}
}从源码运行时,command / args 换成 "node" / ["~/flomo-mcp/dist/index.js"]。
重启客户端后,对 AI 说:
用 flomo 的 whoami 看看连上了吗
返回账号(邮箱脱敏)、笔记总数、标签总数即注册成功。
可选:注入调试口(双击启动即生效)
MCP 自带兜底拉起逻辑,不注入也能用;注入后双击 flomo 图标即带调试口,省去首次调用自动重启的等待:
npx -p @location-txl/flomo-mcp flomo-mcp-patch # 默认 /Applications/flomo.app
npx -p @location-txl/flomo-mcp flomo-mcp-patch -- /你的路径/flomo.app
# 或源码目录内
npm run patch-flomo -- /你的路径/flomo.app脚本幂等,可重复运行;自动备份原版到
app.asar.origflomo 自动更新会覆盖注入,更新后重跑一次即可
恢复原版:
cp "/Applications/flomo.app/Contents/Resources/app.asar.orig" \
"/Applications/flomo.app/Contents/Resources/app.asar"
codesign --force --deep --sign - "/Applications/flomo.app"常见问题
现象 | 原因与处理 |
| flomo 里登录态过期,打开 flomo 重新登录即可 |
| 笔记刚被其他端(手机/网页)改过,重新 |
工具首次调用很慢(~10s) | 触发了兜底:自动 quit + 带调试口重启 flomo,属正常 |
| 手动跑 |
| macOS App Management(TCC)拦截:app 带 quarantine 属性。重命名 app 后用 |
flomo 更新后工具全挂 | 更新覆盖了注入的 asar → 重跑 |
安全提示
9222 调试口对本机所有进程可见,等同 flomo 笔记读写权。介意的话可把注入参数改为
--remote-debugging-pipe(需要同步改src/cdp.ts)本项目不落盘任何凭证;
whoami输出的邮箱已脱敏
开发
常用命令
npm run build # tsc 编译到 dist/(改代码后必跑)
node test-e2e.mjs # 12 个工具全链路测试
npm run patch-flomo # ASAR 注入(可选)测试须知
e2e 测试连接的是真实 flomo 账号:写操作走 create→update→rename→pin→delete 闭环并自动清理,请勿删除测试末尾的清理逻辑。运行前提:flomo 已登录、调试口可用;flomo 不在默认路径时先 export FLOMO_APP_PATH=...。
源码结构
src/
├── index.ts # stdio MCP server 入口 + 12 个工具注册
├── cdp.ts # CDP 客户端:探测/兜底拉起 flomo、页面上下文执行
├── api.ts # 复用页面 $api 的调用层 + flomo 时间/时区格式工具
└── tools.ts # 工具实现与参数 schema
scripts/
└── patch-flomo.mjs # ASAR 注入(幂等)深入文档
TOOLS.md — 全部工具的参数、返回结构、底层接口、维护指南
AGENT.md — 架构约束、逆向得出的不可破坏规则、flomo 更新后的排查步骤
发布流程 — 配置 npm Trusted Publisher,通过 Git 标签发布 npm 和 GitHub Release
License
本项目为个人学习研究项目,与 flomo 官方无关,请自行遵守 flomo 服务条款使用。
Available Tools
12 toolscreate_memoA
创建笔记。标签用 #标签名 语法写在 content 中(flomo 无独立建标签接口,标签由内容隐式创建)
Inputs: content (required). Returns: slug
delete_memoB
删除笔记(移入回收站,可在 flomo 回收站恢复)
Inputs: slug (required). Returns: note, slug
get_memoA
获取单条笔记全文(HTML 与纯文本)。update_memo 前先调用本工具取当前内容
Inputs: slug (required). Returns: slug, tags, created_at, updated_at, +2 more
list_memosA
列出笔记。mode=recent 最近更新(最新在前,最多200条);mode=all 全量按时间升序游标翻页(每页最多100条);传 tag 按标签过滤(前缀匹配含子标签,如 阅读 也含 阅读/读书,全量扫描后按更新时间降序翻页,忽略 mode)
Inputs: tag, mode, limit, cursor. Returns: tag, mode, count, memos, +4 more
list_tagsA
浏览标签树:不传参数=一级标签;传 tag_name=其直接子级;加 recursive=true=其下全部后代。count 为 null 表示计数不可用
Inputs: tag_name, recursive. Returns: tags, count
pin_tagC
置顶标签
Inputs: tag (required). Returns: tag, pinned
rename_tagB
重命名标签(层级用 / 分隔,如 开发/Linux)
Inputs: new_name (required), old_name (required). Returns: to, from
search_memosA
按关键词搜索笔记(匹配正文与标签,大小写不敏感,结果按更新时间降序)。flomo 无远程搜索接口,每次调用全量拉取后本地过滤;翻页时传 next_cursor 且 keyword 保持不变
Inputs: keyword (required), limit, cursor. Returns: count, memos, matched, scanned, +2 more
syncA
手动触发同步(等同点击 flomo 界面左下角同步按钮):拉取服务端最新笔记/标签到本地并推送本地待同步修改,返回同步统计。已有同步在进行中时返回 code=SYNCING
Inputs: no named parameters. Returns: code, synced, message, duration_ms, +4 more
unpin_tagC
取消置顶标签
Inputs: tag (required). Returns: tag, pinned
update_memoA
更新笔记内容(全量替换,自动保留原创建时间/置顶状态/附件)。先 get_memo 取原内容再修改回写
Inputs: slug (required), content (required). Returns: slug
whoamiA
验证 flomo 连接:显示当前登录账号、笔记与标签总数。未登录时报错,需先在 flomo 应用中登录
Inputs: no named parameters. Returns: pro, account, tag_count, memo_count
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool maps to a distinct resource+action, and the pin/unpin pair, get_memo vs update_memo, and the tag operations are all cleanly separated. The only mild overlap is list_memos vs search_memos, which both paginate over the memo set, but the descriptions clarify recent/all/tag-filter vs keyword-filter well enough to avoid misselection.
Almost everything follows a consistent snake_case verb_noun pattern (list_tags, rename_tag, list_memos, create_memo, get_memo, update_memo, delete_memo). Only whoami and sync break the pattern, but both are widely understood conventional names so the set stays readable.
Twelve tools is well within the ideal range and every tool earns its place: six memo CRUD/search operations, four tag operations, plus a health check and an explicit sync. Nothing feels redundant or padded for a single-domain note app.
Memo lifecycle is fully covered (create, list, search, get, update, delete-to-trash) and tags cover list/rename/pin/unpin; tag creation is explicitly noted as implicit via #tag in content. The gap is the absence of tag deletion/merge and any trash restore tool, which agents cannot work around within this surface.
Maintenance
Related MCP Connectors
Connect AI to your flomo notes. Search, create, edit notes and manage tags via MCP.
Securely search, create, and organize your Mem notes and collections from AI assistants.
Search, read, create and edit your Memol notes from Claude. Team note-taking with AI search.
Portable AI memory you own. Keep memories and notes across Claude, ChatGPT, and other AI tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Memos instances for personal note-taking and knowledge management. Supports creating, searching, updating, and organizing memos with tags, dates, and visibility settings through natural language.MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Memos instances for knowledge management. Supports searching, creating, updating, and retrieving memos with markdown content, tags, and visibility controls.45MIT
- AlicenseCqualityDmaintenanceEnables users to create and save notes in Flomo directly through AI chat interactions using natural language commands. Seamlessly integrates with AI assistants like Claude and Cursor to capture thoughts and information.162 npm17MIT
- FlicenseAqualityDmaintenanceEnables to interact with Memos note-taking service, allowing search, creation, retrieval, and updating of notes through natural language.44-