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 ./workflowy

docker run -e WORKFLOWY_API_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": " " } } } }

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 10 tools"] Cache["Export Cache TTL 60s+"] HTTP["HTTP Client 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.