Workflowy

io.github.jbeshirPublished by GitHub account jbeshirv1.0.2Updated Oct 29, 2026

Search, read, create, and organize Workflowy nodes with breadcrumb context.

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & Memory

Overview

AI-generated overview

Local MCP server giving an assistant full read/write access to Workflowy outlines: search, read, create, move, complete and delete nodes.

What you can do
  • Search nodes by keyword or completion date range, with breadcrumb paths showing where each result sits
  • Read a node's full details and list its children in priority order
  • Create and update nodes, including their properties and layout
  • Move nodes to a different parent, and mark them completed or not completed
  • Delete nodes
  • List system locations (home, inbox) and user shortcuts to use as parents
When to use it
Useful when you keep tasks, notes or project outlines in Workflowy and want an assistant to find items, add new bullets, reorganize the tree or tick things off without leaving the chat client.
Requirements
Runs as a local process over stdio (Go install, Docker, or the packaged bundle). Requires a Workflowy API token supplied in the WORKFLOWY_API_TOKEN environment variable; an optional WORKFLOWY_API_URL can point at a custom API endpoint. Network access to the Workflowy API is needed.
Before you install
The server has full write access: the assistant can create, update, move, complete and delete nodes, and deletions may not be recoverable. It holds a Workflowy API token that grants access to your whole account, so keep it out of shared configs. Reads fetch a full export of all nodes, which is cached locally for at least 60 seconds.

Installation

In SourceWeft

  1. Open Workflowy in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

Configuration

VariableRequiredDescription
WORKFLOWY_API_TOKENYesYour Workflowy API token
WORKFLOWY_API_URLNoCustom API URL (default: https://workflowy.com)

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

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

ToolDescription
search_nodesSearch nodes by keyword and/or completion date range (completed_after/completed_before, unix seconds) across name and note fields
get_nodeGet full details of a node by ID
list_childrenList child nodes of a parent, sorted by priority
create_nodeCreate a new node
update_nodeUpdate an existing node's properties
delete_nodeDelete a node
move_nodeMove a node to a different parent
complete_nodeMark a node as completed
uncomplete_nodeMark a node as not completed
list_targetsList system locations (home/inbox) and user shortcuts

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

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

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

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

Source: workflowy/README.md at commit 27dc1b2

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v1.0.2LatestOct 29, 2026
  2. v1.0.1Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts