Workflowy Local Mcp

by rodolfo-terriquez

377 downloads

Not rated

GitHub

About

A desktop app that gives AI assistants full read/write access to your WorkFlowy account with fast local search. Caches your entire outline in local SQLite with full-text search - instant search across hundreds of thousands of nodes without hitting API rate limits.

Details

Author: rodolfo-terriquez
Downloads: 377
Categories: Other, Productivity

- 7 tools for managing Workflowy nodes (read, edit, search, sync, bookmarks)
- Local SQLite cache with fast full-text search across all nodes
- Bookmarks to save frequently-used node locations with context notes
- AI Instructions – create a node to customize LLM behavior across sessions
- Sync-on-access – reads auto-sync so data is always fresh
- Fully local – your API key never leaves your machine

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Workflowy Local Mcp

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

From the repository

Download the latest release, open the app, and enter your Workflowy API key (get one at workflowy.com/api-reference). Go to the Setup tab and copy the configuration snippet for your MCP client (Claude Desktop, Claude Code, Cursor, or any MCP app). Restart your client; the seven Workflowy tools become available: list_bookmarks, save_bookmark, delete_bookmark, read_doc, edit_doc, search_nodes, and sync_nodes.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "workflowy local mcp": {
            "workflowy": {
                "command": "node",
                "args": [
                    "/path/to/workflowy-local-mcp/dist-mcp/server.js"
                ],
                "env": {
                    "WORKFLOWY_API_KEY": "your-api-key"
                }
            }
        }
    }
}

McpServers

{
    "workflowy": {
        "command": "node",
        "args": [
            "/path/to/workflowy-local-mcp/dist-mcp/server.js"
        ],
        "env": {
            "WORKFLOWY_API_KEY": "your-api-key"
        }
    }
}

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.

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

- 7 tools for managing Workflowy nodes (read, edit, search, sync, bookmarks)
- Local SQLite cache with fast full-text search across all your nodes
- 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: .dmg file
- Windows: .msi or .exe installer

2. macOS users: The app is unsigned, so you'll need to bypass Gatekeeper:
- Option 1: Right-click the app → select "Open" → click "Open" in the dialog
- Option 2: Run xattr -cr /path/to/Workflowy\ Local\ MCP.app in Terminal
- If you see "damaged and can't be opened", use Option 2

3. Open the app and enter your Workflowy API key
- Get one at workflowy.com/api-reference

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

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

Available Tools

| Tool | Description |
|------|-------------|
| 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 | Edit nodes via the LLM Doc API. Supports insert, update, and delete operations in a single call. Can create nested structures with one request. |
| search_nodes | Search locally cached nodes by text. Returns results with breadcrumb paths and a preview of each result's children. |
| sync_nodes | Full sync of all Workflowy nodes to local cache (rate limited to 1 request per minute) |

How It Works

The server uses Workflowy's LLM Doc API for reads and writes, with a local SQLite cache for search:

- LLM Doc API: read_doc and edit_doc call Workflowy's /api/llm/doc/read/ and /api/llm/doc/edit endpoints directly for real-time access
- Calendar targets: Use today, tomorrow, next_week, or inbox as node IDs — the API handles date resolution automatically
- 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)
- 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
- 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 cache status and trigger a manual sync
- Logs — view MCP server logs in real time (auto-refreshes every 3 seconds)

AI Instructions

You can create a node called "AI Instructions" in Workflowy to set persistent preferences for how LLMs interact with your data. For example:

- "Always add new tasks to my #inbox"
- "Use checkboxes for tasks, not bullets"
- "My calendar is under 'Daily Notes > 2025'"

The LLM will search for this node, save it as a reserved ai_instructions bookmark, and automatically load it at the start of every conversation.

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).

The API key can also be set via the WORKFLOWY_API_KEY environment variable instead of the app config.

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.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

Workflowy Local MCP

Why This Exists

Features

Installation

Available Tools

How It Works

Desktop App

AI Instructions

Data Storage

Works With

Building from Source

Install

More like this

Sequential Thinking

Time

Filesystem

EverArt

Google Drive

Reactive Resume