Workflowy

workflowy-mcp

An MCP server that provides full read/write access to Workflowy. Search, create, organize, move, and complete nodes from any MCP-compatible client such as Claude Desktop or Claude Code. The server communicates over stdio and caches Workflowy's export endpoint to stay within API rate limits.

Getting Started

Requirements

• A Workflowy API token from workflowy.com/api-key

Configuration

Install from source

Requires Go 1.27.3+.

go install github.com/jbeshir/mcp-servers/workflowy/cmd/workflowy-mcp@latest

Docker

docker build -t workflowy-mcp ./workflowydocker run -e WORKFLOWY_API_TOKEN=<your-token> workflowy-mcp

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{  "mcpServers": {    "workflowy": {      "command": "/path/to/workflowy-mcp",      "env": { "WORKFLOWY_API_TOKEN": "<your-token>" }    }  }}

Claude Code

claude mcp add workflowy -- env WORKFLOWY_API_TOKEN=<your-token> /path/to/workflowy-mcp

Tools

Key Concepts

• Nodes — The basic unit in Workflowy. Every bullet, heading, todo, and code block is a node. Nodes form a tree: each node can have children, and every node except the root has a parent.
• Targets — Named system locations (home, inbox) and user-defined shortcuts. You can use target keys anywhere a parent ID is accepted, so you can create nodes in your inbox without knowing its UUID.
• Layout modes — Each node has a display mode: bullets (default), todo, h1, h2, h3, code-block, or quote-block.
• Breadcrumb paths — Search results include the full chain of ancestor names (e.g. Projects > Backend > Auth), giving context for where a node sits in the hierarchy.
• Hierarchical completion — Completing a parent node implicitly completes all its children. The server understands this when filtering search results, so a child under a completed parent is treated as completed even if it has no completion timestamp of its own.

Architecture Overview

graph LR    Client["MCP Client"]    Server["MCP Server<br/>10 tools"]    Cache["Export Cache<br/>TTL 60s+"]    HTTP["HTTP Client<br/>Bearer token auth"]    API["Workflowy REST API"]
    Client -->|"JSON-RPC over stdio"| Server    Server -->|"reads"| Cache    Server -->|"writes"| HTTP    Cache -->|"cache miss"| HTTP    HTTP -->|"HTTPS"| API

The server has three internal layers:

• MCP Server (internal/server/) — Registers 10 tools, parses arguments, formats JSON responses with breadcrumb paths.
• Export Cache (internal/cache/) — TTL-based cache of the full node export. Uses double-checked locking (RWMutex) to coalesce concurrent fetches. Minimum TTL is 60 seconds to respect Workflowy's rate limit on the export endpoint.
• HTTP Client (internal/client/) — Thin REST client. All requests use Bearer token authentication. Read operations go through the cache; write operations call the API directly and then invalidate the cache.

Data Flow

Read path (search, get, list)

sequenceDiagram    participant C as MCP Client    participant S as MCP Server    participant Ca as Export Cache    participant H as HTTP Client    participant A as Workflowy API
    C->>S: search_nodes(query)    S->>Ca: GetAllNodes()    alt Cache hit (within TTL)        Ca-->>S: Cached nodes    else Cache miss or expired        Ca->>H: ExportNodes()        H->>A: GET /api/v1/nodes-export        A-->>H: All nodes (JSON)        H-->>Ca: []Node        Ca-->>S: Fresh nodes    end    S-->>C: Matching nodes with breadcrumb paths

Write path (create, update, delete, move, complete)

sequenceDiagram    participant C as MCP Client    participant S as MCP Server    participant Ca as Export Cache    participant H as HTTP Client    participant A as Workflowy API
    C->>S: create_node(name, parentId)    S->>H: CreateNode(request)    H->>A: POST /api/v1/nodes    A-->>H: Created node ID    H-->>S: CreateNodeResponse    S->>Ca: Invalidate()    S-->>C: "Created node with ID: ..."

Write operations bypass the cache entirely, call the Workflowy API directly, and then invalidate the cache so the next read fetches fresh data.