Workflowy Local MCP

A desktop app that gives AI assistants full read/write access to your Workflowy account with fast local search. Unlike simple API wrappers, it caches your entire outline in a local SQLite database with full-text search - so your AI can instantly search across hundreds of thousands of nodes without hitting API rate limits. Your API key never leaves your machine.

More from this collection: Workflowy tools by Rodolfo.

Why This Exists

Workflowy's API has no search endpoint and a strict 1 request/minute rate limit on full exports. That makes direct API access painfully slow for AI assistants that need to explore your outline. This server solves that with local caching, instant full-text search, bookmarks with context, and AI-configurable instructions - all through a simple desktop app.

Features

• 16 tools for managing Workflowy nodes, mirrors, accounts, cache, and backups
• Production or beta public API — production handles mirror writes; beta adds richer mirror identity metadata
• Local SQLite cache with fast full-text search across all your nodes
• Daily full-account backups stored locally as JSON snapshots
• Configurable backup retention — optionally keep only the newest N backups
• Bookmarks to save frequently-used node locations with context notes
• AI Instructions — create an "AI Instructions" node in Workflowy to customize LLM behavior across sessions
• Sync-on-access — reads auto-sync from the Workflowy API so data is always fresh
• Customizable server instructions and tool descriptions to tune AI behavior
• MCP logging — view server activity in the desktop app in real time
• Fully local — your API key never leaves your machine

Installation

1. Download the latest release from GitHub Releases

   • macOS (Apple Silicon): download the aarch64.dmg file
   • macOS (Intel): download the x64.dmg file
   • Linux (x64): download the amd64.AppImage file
   • Windows (x64): download either the .msi installer or the .exe setup file
   • Ignore .sig, .tar.gz, and latest.json files unless you are debugging updates or verifying signatures manually

2. macOS users: The app is signed, so you can install and open the matching .dmg normally

3. Linux users: make the AppImage executable (chmod +x Workflowy.MCP_*_amd64.AppImage) and run it directly

4. Windows users: the .msi is the standard Windows installer; the .exe is an alternative setup package for the same x64 build

   • Closing the app window keeps Workflowy MCP running in the system tray. Left-click the tray icon to reopen it, or use Quit in the tray menu to exit completely.

5. Open the app and enter your Workflowy API key

   • Get one at workflowy.com/api-reference

6. Go to the Setup tab and follow the instructions for your MCP client (Claude Code, Claude Desktop, Cursor, or any app that supports MCP)

7. Restart your MCP client — the Workflowy tools are now available

Available Tools

Tool	Description
list_accounts	List configured accounts plus sanitized configuration-source, persistence, and reload diagnostics
reload_configuration	Reload accounts and API environment from disk without restarting the MCP client
list_bookmarks	List all saved bookmarks and the user's custom AI instructions. Call this at the start of every conversation.
save_bookmark	Save a node ID with a friendly name and context notes for future sessions
delete_bookmark	Delete a saved bookmark by name
read_doc	Read a node and its children via the LLM Doc API. Supports calendar targets (today, tomorrow, next_week, inbox) and configurable depth (1-10). Returns tag-as-key JSON format.
edit_doc	Insert, update, complete, delete, and move nodes. Ordinary single-node edits use public API v1; grouped edits, nested structures, tables, and insert-after placement use the LLM Doc API automatically.
mirror_info	Inspect whether a node is a mirror, an origin with mirrors, or a regular node (beta public API)
create_mirror	Create a synchronized mirror under another parent (production or beta public API)
remove_mirror	Remove one confirmed mirror root while preserving its origin (production or beta public API)
search_nodes	Search locally cached nodes by text. Returns breadcrumb paths, child previews, timestamps, and mirror/origin metadata when present.
sync_nodes	Full sync of all Workflowy nodes to local cache (rate limited to 1 request per minute)
list_backups	List stored full-account backup snapshots with IDs, timestamps, sizes, and file paths
create_backup	Create a fresh full-account backup snapshot on demand
restore_backup	Restore the local search/cache database from a stored backup snapshot
export_backup	Copy a stored backup snapshot to another file path or directory

How It Works

The server combines Workflowy's public API v1 with the LLM Doc API, plus a local SQLite cache for search:

• Hybrid edit routing: one flat insert, update, completion, deletion, or move uses public API v1; grouped operations, nested children, tables, paragraph nodes, completed inserts, mixed completion/content updates, and insert-after placement stay on /api/llm/doc/edit
• LLM Doc API: read_doc calls /api/llm/doc/read/ for recursive tag-as-key reads, and advanced edit_doc requests retain the document endpoint's richer structure support
• Public API environments: ordinary edits, cache sync, backups, validation, and mirror create/remove can use production (default) or beta; richer mirror inspection requires beta; select the environment under Accounts and refresh MCP tools after saving
• Account hot reload: the server detects saved account changes before tool calls, reloads them safely, and notifies compatible MCP clients that tool schemas changed
• Mirrors: production supports create/remove, while beta adds richer data.mirror.origin_id, data.mirror.mirror_ids, and list-level identity metadata; cache sync and search preserve these relationships, including inaccessible origins reported as origin_id: null
• Calendar targets: Use today, tomorrow, next_week, or inbox as node IDs — public v1 creates missing Calendar destinations on demand for ordinary inserts and moves
• Batch operations: edit_doc can perform multiple insert/update/delete operations in a single API call
• Local cache for search: search_nodes uses a SQLite cache that auto-syncs when stale (>1 hour)
• Daily backups: a complete nodes-export snapshot is saved once per day while the server is running
• Retention control: set an optional max backup count; when unset, all backups are kept
• Rate limiting: The Workflowy nodes-export API (used for cache sync) is limited to 1 request per minute; the LLM Doc API has no rate limit

Desktop App

The Tauri-based desktop app provides a UI for configuration and monitoring:

• API Key — enter and validate your Workflowy API key
• API Environment — keep the stable production default or opt into the beta public API for early features
• Tools — customize server instructions and individual tool descriptions to tune AI behavior
• Setup — copy-paste configuration snippets for Claude Code, Claude Desktop, and Cursor
• Bookmarks — view, edit context, and delete saved bookmarks
• Cache — view the persistent cache status; sync it through the MCP sync_nodes tool
• Logs — view MCP server logs in real time (auto-refreshes every 3 seconds)

AI Section

The real power of the MCP server comes from building a persistent AI section in your Workflowy account. This gives your AI assistant a stable, session-persistent context — it knows your name, your structure, your workflows, and what to do every morning without you having to explain it each time.

The system has three parts, each saved as a named bookmark:

Bookmark	Node	Purpose
ai_instructions	AI Instructions	Tells the AI who you are, how your account is structured, and what workflows to run
ai_memory	AI Memory	Persistent notes the AI writes to itself - MCP quirks, patterns, things it learned about you
ai_skills	AI Skills	Reusable workflows with step-by-step instructions for APIs or tools you use regularly

AI Instructions is the core. At minimum, it should describe your account layout and set behavioral preferences:

🤖 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 starts empty and fills up naturally. The AI writes to it when it discovers something worth remembering — an MCP quirk it hit, a pattern in how you work, a useful node ID. It persists across sessions so you never have to re-explain the same thing twice.

AI Skills holds reusable workflows. A useful starting skill is a Morning Briefing — a set of steps the AI runs every session start: check specific lists, triage the inbox, scan yesterday's log or calendar for anything left hanging, run any recurring checks (API calls, commit logs, whatever your workflow involves).

Data Storage

All data is stored locally in the app data directory:

Platform	Path
macOS	~/Library/Application Support/com.workflowy.local-mcp/
Windows	%APPDATA%\com.workflowy.local-mcp\
Linux	~/.local/share/com.workflowy.local-mcp/

Files stored: config.json (settings), bookmarks.db (SQLite database with bookmarks and node cache), mcp-logs.json (server logs), backups/ (daily full-account export snapshots plus metadata). Bookmarks remain available in both environments; switching environments clears and refreshes only cached nodes. Beta backup snapshots are isolated in beta/backups/ so they cannot replace production backups.

The API key can also be set via the WORKFLOWY_API_KEY environment variable when the app config has no structured accounts array. Structured accounts saved by the desktop app take precedence; list_accounts reports a sanitized warning when both sources are present. Set WORKFLOWY_API_ENVIRONMENT=beta to override the saved public API environment for a server process.

Works With

• Claude Desktop
• Claude Code
• Cursor
• Any application that supports the Model Context Protocol

Building from Source

Requires Node.js 18+ and Rust.

npm install
npm run tauri build

This runs the frontend build (tsc && vite build), bundles the MCP server with esbuild (npm run build:mcp), and packages everything into a Tauri desktop app.