Workflowy Local Mcp

Workflowy Local MCP

一款桌面应用，可让 AI 助手全面读写你的 Workflowy 账户，并提供快速本地搜索。它不同于简单的 API 封装，会将整个大纲缓存到本地 SQLite 数据库，并建立全文搜索功能——这样，你的 AI 就能即时搜索数十万个节点，而无需触发 API 速率限制。你的 API 密钥绝不会离开你的设备。

此系列的更多内容：Rodolfo 的 Workflowy 工具。

为什么要开发它

Workflowy 的 API 没有搜索端点，而且完整导出严格限制为每分钟 1 次请求。对于需要探索大纲的 AI 助手来说，直接访问 API 的速度慢得令人难以忍受。这个服务通过本地缓存、即时全文搜索、附带上下文的书签，以及可由 AI 配置的指令解决了这一问题，所有功能都通过一个简单的桌面应用提供。

功能

• 16 个工具，用于管理 Workflowy 节点、镜像、账户、缓存和备份
• 生产版或 Beta 公共 API——生产版支持镜像写入；Beta 版提供更丰富的镜像身份元数据
• 本地 SQLite 缓存，可快速全文搜索所有节点
• 每日完整账户备份，以 JSON 快照的形式存储在本地
• 可配置的备份保留策略——可选择仅保留最新的 N 份备份
• 书签，用于保存常用节点位置并附上上下文备注
• AI 指令——在 Workflowy 中创建“AI 指令”节点，以自定义跨会话的大模型行为
• 访问时同步——读取操作会自动从 Workflowy API 同步，确保数据始终为最新
• 可自定义的服务指令和工具描述，用于调整 AI 行为
• MCP 日志记录——在桌面应用中实时查看服务活动
• 完全本地运行——你的 API 密钥绝不会离开你的设备

安装

1. 从 GitHub Releases 下载最新版本

   • macOS（Apple Silicon）：下载 aarch64.dmg 文件
   • macOS（Intel）：下载 x64.dmg 文件
   • Linux（x64）：下载 amd64.AppImage 文件
   • Windows（x64）：下载 .msi 安装程序或 .exe 安装文件
   • 除非你要调试更新或手动验证签名，否则请忽略 .sig、.tar.gz 和 latest.json 文件

2. macOS 用户：应用已签名，可正常安装并打开对应的 .dmg 文件

3. Linux 用户：将 AppImage 设置为可执行文件（chmod +x Workflowy.MCP_*_amd64.AppImage），然后直接运行

4. Windows 用户：.msi 是标准 Windows 安装程序；.exe 是适用于同一 x64 构建版本的另一种安装包

   • 关闭应用窗口后，Workflowy MCP 会继续在系统托盘中运行。左键点击托盘图标可重新打开应用，或使用托盘菜单中的 退出 完全退出。

5. 打开应用并输入你的 Workflowy API 密钥

   • 前往 workflowy.com/api-reference 获取密钥

6. 前往 Setup 选项卡，按照你的 MCP 客户端（Claude Code、Claude Desktop、Cursor，或任何支持 MCP 的应用）的说明进行操作

7. 重启 MCP 客户端——现在即可使用 Workflowy 工具

可用工具

工具	描述
list_accounts	列出已配置的账户，以及经过脱敏的配置来源、持久化和重新加载诊断信息
reload_configuration	从磁盘重新加载账户和 API 环境，无需重启 MCP 客户端
list_bookmarks	列出所有已保存的书签和用户自定义的 AI 指令。每次对话开始时都要调用此工具。
save_bookmark	保存节点 ID，并附上便于识别的名称和上下文备注，供之后的会话使用
delete_bookmark	按名称删除已保存的书签
read_doc	通过 LLM Doc API 读取节点及其子节点。支持日历目标（today、tomorrow、next_week、inbox）和可配置的深度（1-10）。返回以标签为键的 JSON 格式。
edit_doc	插入、更新、完成、删除和移动节点。普通的单节点编辑使用 public API v1；分组编辑、嵌套结构、表格和插入到指定节点之后会自动使用 LLM Doc API。
mirror_info	检查节点是镜像、带有镜像的原始节点，还是普通节点（beta public API）
create_mirror	在另一个父节点下创建同步镜像（production 或 beta public API）
remove_mirror	移除一个已确认的镜像根节点，同时保留其原始节点（production 或 beta public API）
search_nodes	按文本搜索本地缓存的节点。返回面包屑路径、子节点预览、时间戳，以及可用时的镜像/原始节点元数据。
sync_nodes	将所有 Workflowy 节点完整同步到本地缓存（限速为每分钟 1 次请求）
list_backups	列出已存储的完整账户备份快照，包括 ID、时间戳、大小和文件路径
create_backup	按需创建新的完整账户备份快照
restore_backup	从已存储的备份快照恢复本地搜索/缓存数据库
export_backup	将已存储的备份快照复制到其他文件路径或目录

工作原理

该服务将 Workflowy 的 public API v1 与 LLM Doc API 结合使用，并通过本地 SQLite 缓存支持搜索：

• 混合编辑路由：单个扁平节点的插入、更新、完成、删除或移动使用 public API v1；分组操作、嵌套子节点、表格、段落节点、插入后立即完成、混合完成状态/内容更新，以及插入到指定节点之后，均使用 /api/llm/doc/edit
• LLM Doc API：read_doc 调用 /api/llm/doc/read/，以递归方式读取以标签为键的结构；高级 edit_doc 请求则保留文档端点更丰富的结构支持
• Public API 环境：普通编辑、缓存同步、备份、验证，以及镜像的创建/移除可使用 production（默认）或 beta；更丰富的镜像检查需要使用 beta；在 Accounts 下选择环境并保存后，刷新 MCP 工具
• 账户热重载：服务会在工具调用前检测已保存的账户变更，并安全地重新加载，同时通知兼容的 MCP 客户端工具架构已变更
• 镜像：production 支持创建/移除；beta 则提供更丰富的 data.mirror.origin_id、data.mirror.mirror_ids 和列表级身份元数据；缓存同步和搜索会保留这些关系，包括将无法访问的原始节点报告为 origin_id: null
• 日历目标：将 today、tomorrow、next_week 或 inbox 用作节点 ID — public v1 会在执行普通插入和移动时，按需创建缺失的日历目标
• 批量操作：edit_doc 可以在一次 API 调用中执行多个插入/更新/删除操作
• 本地搜索缓存：search_nodes 使用 SQLite 缓存，并会在缓存过期（超过 1 小时）时自动同步
• 每日备份：服务运行时，每天保存一次完整的 nodes-export 快照
• 保留控制：可设置可选的最大备份数量；未设置时会保留所有备份
• 速率限制：Workflowy 的 nodes-export API（用于缓存同步）限速为每分钟 1 次请求；LLM Doc API 没有速率限制

桌面应用

基于 Tauri 的桌面应用提供用于配置和监控的界面：

• API Key — 输入并验证你的 Workflowy API key
• API 环境 — 保持稳定的生产环境默认设置，或选择加入 Beta 公共 API 以抢先使用新功能
• 工具 — 自定义服务说明和各个工具的描述，以调整 AI 的行为
• 设置 — 复制并粘贴 Claude Code、Claude Desktop 和 Cursor 的配置片段
• 书签 — 查看、编辑上下文并删除已保存的书签
• 缓存 — 查看持久缓存状态；通过 MCP sync_nodes 工具同步
• 日志 — 实时查看 MCP 服务日志（每 3 秒自动刷新）

AI 部分

MCP 服务真正的强大之处，在于在你的 Workflowy 账户中构建一个持久的 AI 部分。这能为你的 AI 助手提供稳定且跨会话持久的上下文——它了解你的姓名、结构和工作流，也知道每天早上该做什么，无需你每次都重新说明。

该系统由三个部分组成，每个部分都保存为一个命名书签：

书签	节点	用途
ai_instructions	AI Instructions	告诉 AI 你是谁、账户结构如何，以及要运行哪些工作流
ai_memory	AI Memory	AI 写给自己的持久笔记——MCP 的特性、模式以及它对你的了解
ai_skills	AI Skills	可复用的工作流，包含使用常用 API 或工具的分步说明

AI Instructions 是核心。至少应描述你的账户布局并设定行为偏好：

🤖 AI Instructions
  ├── When Starting Conversations
  │   ├── Read these instructions and check AI Memory for quirks
  │   └── Run the Morning Briefing skill — handles Now items, inbox triage, log follow-ups
  ├── About This Account
  │   └── Personal Workflowy for [Name] — daily planning, projects, knowledge base
  ├── Key Locations
  │   ├── 📥 Inbox — capture point for all ideas
  │   ├── 🌞 Daily — weekly planning + Now (today's focus) + Calendar log
  │   └── 📁 Topics — knowledge base and reference material
  ├── User Preferences
  │   └── Concise, conversational — clear takeaways, not walls of data
  └── Constraints
      ├── Always confirm before deleting
      └── Use regular bullets only (no headings) when logging

AI Memory 初始为空，并会自然积累内容。AI 在发现值得记住的事情时会将其写入其中——遇到的 MCP 特性、你的工作模式、有用的节点 ID。它会跨会话保留，因此你不必反复解释同一件事。

AI Skills 存放可复用的工作流。一个实用的入门技能是 晨间简报——AI 在每次会话开始时运行的一系列步骤：检查指定列表、整理收件箱、扫描昨天的日志或日历，查找尚未处理的事项，并运行任何定期检查（API 调用、提交日志，或工作流涉及的其他内容）。

数据存储

所有数据都存储在应用数据目录中：

平台	路径
macOS	~/Library/Application Support/com.workflowy.local-mcp/
Windows	%APPDATA%\com.workflowy.local-mcp\
Linux	~/.local/share/com.workflowy.local-mcp/

存储的文件：config.json（设置）、bookmarks.db（包含书签和节点缓存的 SQLite 数据库）、mcp-logs.json（服务日志）、backups/（每日完整账户导出快照及元数据）。书签在两种环境中都会保留；切换环境只会清除并刷新缓存节点。Beta 备份快照单独存放在 beta/backups/ 中，因此不会替换生产备份。

如果应用配置中没有结构化的 accounts 数组，也可以通过 WORKFLOWY_API_KEY 环境变量设置 API key。桌面应用保存的结构化账户具有更高优先级；如果两种来源同时存在，list_accounts 会报告一条经过净化的警告。设置 WORKFLOWY_API_ENVIRONMENT=beta 可覆盖已保存的公共 API 环境，供服务进程使用。

兼容应用

• Claude Desktop
• Claude Code
• Cursor
• 任何支持 Model Context Protocol 的应用程序

从源代码构建

需要 Node.js 18+ 和 Rust。

npm install
npm run tauri build

这会运行前端构建（tsc && vite build），使用 esbuild 打包 MCP 服务（npm run build:mcp），并将所有内容打包成 Tauri 桌面应用。