WorkflowyMCP

Workflowy MCP Server

A Rust MCP server that gives Claude (Code or Desktop) read/write access to your Workflowy graph, plus a generic template for turning that raw access into a working second brain.

There are two ways to use it:

1. Bare MCP server. Wire the binary into your MCP host and call the 41

tools directly. No templates, no opinions.

1. Second brain. Hand [BOOTSTRAP.md](BOOTSTRAP.md) to Claude. The

assistant follows the script: builds the binary, wires the host, sets up your secondBrain directory at whatever path you choose (exposed to the server via $SECONDBRAIN_DIR), and installs the wflow skill that drives every subsequent session.

The methodology in option 2 is opinionated; the server itself is not. The repo only ships generic templates — your node IDs, drafts, and session logs live wherever $SECONDBRAIN_DIR points, never in this repo.

---

Quick install

You need: Rust 1.75+ (rustup install stable), a Workflowy account with an API key (Settings → API in Workflowy), and an MCP host (Claude Code or Claude Desktop).

git clone https://github.com/dromologue/workflowyMCP.git ~/code/workflowy-mcp-server
cd ~/code/workflowy-mcp-server
cargo build --release
echo "WORKFLOWY_API_KEY=" > .env

The binary reads .env from the directory it's launched from. The clone path above (~/code/workflowy-mcp-server) is the working directory for the host's MCP launch — the host runs the binary from there, so .env resolves correctly. Recommended alternative: put the same key in your MCP host's env block (see the next section), so the binary works regardless of where it's launched from.

Wire the resulting target/release/workflowy-mcp-server into your MCP host:

• Claude Code: claude mcp add workflowy -- $(pwd)/target/release/workflowy-mcp-server
• Claude Desktop: edit

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). See [BOOTSTRAP.md](BOOTSTRAP.md) for the JSON shape.

Verify by calling the workflowy_status tool — the host should return status: "ok", api_reachable: true, authenticated: true. If authenticated: false, your API key is wrong or not reaching the binary; check the env-var section below.

That's it for plain MCP usage.

---

Environment variables

The server reads four env vars at runtime. The repository ships no machine-specific defaults: a path or node ID you don't set is a feature you don't use. Set them in the env block of your MCP host config (Claude Code: ~/.claude.json; Claude Desktop: claude_desktop_config.json) and, when you also use the wflow-do CLI from a shell, in your shell profile (~/.zshrc or ~/.bashrc).

| Variable | Required? | What it controls | |----------|-----------|------------------| | WORKFLOWY_API_KEY | Yes | Bearer token for the Workflowy API. | | SECONDBRAIN_DIR | Optional | Absolute path to your operational secondBrain directory (drafts, session logs, briefs, memory). When set, the review tool's bucket-d session-log scan and the wflow-do index default output path read from $SECONDBRAIN_DIR/session-logs/. Unset or empty disables those features (graceful skip). | | WORKFLOWY_INDEX_PATH | Optional | Absolute path to the persistent name-index JSON. Conventionally $SECONDBRAIN_DIR/memory/name_index.json. Unset or empty disables persistence — the index then lives only in memory for the lifetime of each process. | | WORKFLOWY_REVIEW_ROOT | Optional | Default root node for the review and audit_mirrors tools when root_id is omitted (your review-anchor / "Distillations" node). No hardcoded fallback — if unset, those two tools require an explicit root_id. |

Example MCP host env block (Claude Code or Desktop):

"env": {
  "WORKFLOWY_API_KEY": "",
  "SECONDBRAIN_DIR": "/absolute/path/to/secondBrain",
  "WORKFLOWY_INDEX_PATH": "/absolute/path/to/secondBrain/memory/name_index.json",
  "WORKFLOWY_REVIEW_ROOT": ""
}

Example shell profile (so the CLI agrees with the MCP server):

export SECONDBRAIN_DIR="/absolute/path/to/secondBrain"
export WORKFLOWY_INDEX_PATH="$SECONDBRAIN_DIR/memory/name_index.json"

Neither path needs to be inside the user's home directory — a Dropbox / iCloud / Google Drive folder works as long as the host process can read and write it. Paths with spaces are fine in the MCP env block (JSON quoting handles it) and in the shell profile (the export line quotes the value).

---

Set up the second brain (recommended)

Hand [BOOTSTRAP.md](BOOTSTRAP.md) to Claude. The assistant runs through six steps: build, wire the host, bootstrap your secondBrain directory at the path you set in $SECONDBRAIN_DIR, populate your structural node IDs, install the wflow skill, and (optionally) pre-warm the persistent name index. After bootstrap, the assistant follows [templates/skills/wflow/SKILL.md](templates/skills/wflow/SKILL.md) as the operating manual.

The detailed long-form walkthrough — large-tree convergence, troubleshooting — lives in [docs/SETUP.md](docs/SETUP.md).

---

User-specific files (what you create)

The repo is generic. Everything specific to your Workflowy tree, your intellectual frameworks, and your in-progress work lives outside it. These are the files you populate (or accept the bundled defaults from the wflow skill, then customise):

| File | Lives at | What it holds | Why it's external | |------|----------|---------------|-------------------| | workflowy_node_links.md | $SECONDBRAIN_DIR/memory/ (canonical) and ~/.claude/skills/wflow/ (bundled fallback for surfaces that can't read $SECONDBRAIN_DIR) | Cached UUIDs for your structural Workflowy nodes (Inbox, Tasks, Reading List, Distillations, Themes, etc.) plus a Triage Sources table that defines which nodes Workflow 6 sweeps. Editing this list is how you add a new triage target — capture sub-node, Slack-saved-items mirror — without changing the skill. | The skill is portable; your tree isn't. The skill references this file so different users can have entirely different Workflowy structures. | | distillation_taxonomy.md | $SECONDBRAIN_DIR/memory/ (canonical) and ~/.claude/skills/wflow/ (bundled fallback) | Your distillation pillars (the top-level conceptual buckets you organise atomic notes into), themes (cross-cutting tags), inbound routing rules (which topic goes to which pillar), and the named frameworks you work with. | The skill describes the synthesis workflow generically and reads your actual taxonomy from this file. Pillars and frameworks are deeply personal; embedding one user's into the skill would force everyone else to inherit them. | | name_index.json | $WORKFLOWY_INDEX_PATH (typically $SECONDBRAIN_DIR/memory/name_index.json) | Auto-managed by the MCP server. Persistent name index that turns Workflowy URL fragments and short-hashes into full UUIDs in O(1). Survives restarts; checkpoints every 30 s; refreshes via background walks every 30 minutes. | You don't write this file directly — the server maintains it. But it lives in your secondBrain so it's portable across your machines (e.g. via Google Drive / Dropbox / iCloud). | | drafts/, session-logs/, briefs/ | $SECONDBRAIN_DIR/ | Your in-flight distillation work (drafts/), per-session audit trails (session-logs/), and external-facing handoff documents (briefs/). | The skill's end-of-session discipline writes to these locations. They're per-user by definition. | | tasks/todo.local.md | inside this repo (gitignored) | Cross-session engineering follow-ups for the workflowy-mcp-server itself — issues you noticed, ideas to revisit, items the previous habit would have filed as Workflowy "system tasks." | Engineering todos belong with the code, not in your Workflowy outline; gitignored so each contributor's local list stays out of the tracked tree. |

Precedence rule. When the skill needs data from the two memory files, it prefers the canonical at $SECONDBRAIN_DIR/memory/.md. If that path isn't readable (e.g. a host with no filesystem access), it falls back to the bundled copy at ~/.claude/skills/wflow/.md. The bundled copy is overwritten on each skill ZIP rebuild, so canonical edits need to be re-bundled before they reach surfaces that depend on the fallback.

---

What ships in this repo

workflowyMCP/
├── BOOTSTRAP.md              ← LLM-facing install script (hand to Claude)
├── README.md                 ← this file
├── docs/SETUP.md             ← long-form bootstrap notes
├── specs/specification.md    ← authoritative behavioural spec
├── templates/
│   ├── secondbrain/          ← skeleton copied to $SECONDBRAIN_DIR
│   │   ├── README.md
│   │   ├── memory/workflowy_node_links.md     (template; user fills in)
│   │   ├── memory/distillation_taxonomy.md    (template; user fills in)
│   │   ├── drafts/  session-logs/  briefs/
│   └── skills/wflow/SKILL.md ← the operating manual the assistant follows
└── src/                       ← Rust MCP server source

User-specific data (node IDs, drafts, session logs, briefs) belongs at whatever path you set via $SECONDBRAIN_DIR. The repo content stays generic so the next person who clones it gets a clean starting point.

---

Tool reference

The server exposes 41 tools. node_id accepts any of: full UUID (with or without hyphens), 12-char URL-suffix short hash, or 8-char prefix. parent_id (and any other parent-scoped argument) accepts null or omission as "workspace root" across the whole tool surface — create_node, batch_create_nodes, insert_content, list_children, and the rest behave the same way.

| Category | Tools | |----------|-------| | Search & navigate | node_at_path, resolve_link, search_nodes, find_node, get_node, list_children, tag_search, get_subtree, find_backlinks, path_of, find_by_tag_and_path, read_batch | | Create & edit | create_node, batch_create_nodes, insert_content, smart_insert, convert_markdown, edit_node, move_node, reorder_nodes, delete_node, complete_node, duplicate_node, create_from_template, bulk_update, bulk_tag, transaction, export_subtree | | Mirror discipline | create_mirror (convention-based: duplicates the canonical's name into a new parent and writes mirror_of: to the new node's note), audit_mirrors | | Todos & scheduling | list_todos, list_upcoming, list_overdue, daily_review, since | | Project management | get_project_summary, get_recent_changes | | Diagnostics & ops | workflowy_status, health_check, cancel_all, build_name_index, review, get_recent_tool_calls |

Native task completion. complete_node(node_id) toggles the Workflowy completed boolean — the legacy #done tag-as-completion workaround is deprecated for tasks. bulk_update(operation: "complete"|"uncomplete", filter: …) toggles a filtered set in one call; transaction accepts the same ops with rollback. Wire payload is POST /nodes/{id} with {"completed": true|false}.

Reordering siblings (reorder_nodes). Workflowy's move_node priority is position-relative-to-siblings and renormalises after every call, so a naive forward priority=0,1,2,… loop fights itself when you try to batch-reorder a set. reorder_nodes(parent_id, node_ids[]) takes the desired head-first order and walks it in reverse, issuing move_node with priority=0 per id — every move plants its node at position 0, the previously-planted nodes shift one step right, and after N moves the head of the parent's children is the requested sequence. Side effect: ids not currently under parent_id are reparented as part of the reorder (the primitive is built on move_node, not a sibling- only assertion). Capped at 200 ids per call. Returns Complete or Partial { reason: cancelled | timeout } with per-id ok / error / skipped entries; partial outcomes are safe to re-issue with the full list because each reverse-priority-0 move is idempotent. The orchestration lives once in crate::workflows::reorder_nodes_via_priority and is shared with wflow-do reorder --parent --node --node .

Mirror creation (convention). Workflowy's REST API does not expose native mirror creation, so create_mirror(canonical_node_id, target_parent_id) implements the documented mirror_of: / canonical_of: note convention that audit_mirrors already understands: a new node is created under the target parent with the same name as the canonical, and its description carries mirror_of: . Edits to the canonical do not propagate to the mirror — the link is structural and human-curated, not live. Pass an optional pillar to write a canonical_of: marker to the canonical when it lacks one; existing markers are never overwritten. Pass dry_run=true to preview the resolved canonical, target_parent, and mirror name (verbatim copy of the canonical's name) without writing — useful when batching multiple mirror passes across a synthesis. The mirror's create + the optional canonical edit (and the dry-run preview) run through the shared [crate::workflows](src/workflows.rs) module, the same code path the wflow-do create-mirror [--dry-run] CLI calls.

scope_resolved diagnostic field. Every tool that accepts an Option for parentid (create_node, batch_create_nodes, insert_content, create_mirror, list_children, find_node, search_nodes) returns a scope_resolved field naming what the server actually targeted: workspace_root when the resolved scope was None (caller passed null or omitted), or scoped: otherwise. Read this field after every call where parentid was null/omitted to verify the server resolved to where you intended — pre-2026-05-09 callers had no way to audit this without inspecting the wire payload.

insert_content payload cap. The hard cap is 80 lines per call, lowered from 200 on 2026-05-04 after the failure-report 2026-05-03 session observed ≥80-line payloads failing at the MCP transport layer with no diagnostic. Above the cap, the call returns a typed error with a chunking instruction; chunk to ≤80 lines and pass the previous batch's last_inserted_id as the next call's parent_id to keep the hierarchy stitched together.

Truncation envelope. Every walk-shaped tool that emits JSON includes the same four fields when its 20 s walk budget fires:

{
  "truncated": true,
  "truncation_limit": 10000,
  "truncation_reason": "timeout",
  "truncation_recovery_hint": "Call build_name_index(parent_id=...) … then re-issue with use_index=true …"
}

Read truncation_reason and truncation_recovery_hint on every walk response. For name-based queries (search_nodes, find_node), use_index=true answers in O(1) from the persistent name index without burning the walk budget — populate it first with build_name_index(parent_id=). Index path is name-only; description-content matching still needs a live walk.

For large workspaces, prefer node_at_path (path of names → UUID, ~1 second on any tree size) and resolve_link (Workflowy URL + optional parent path → full node info) over search_nodes. They cost O(depth) API calls instead of O(tree).

Conventions parsed from node text:

• Tags: #inbox, #review, #urgent
• Assignees: @alice, @bob
• Due dates: due:2026-03-15, #due-2026-03-15, or bare 2026-03-15

(priority order)

---

Reliability properties

Every API-touching handler runs inside a uniform run_handler wrapper that observes the server-wide cancel registry and applies a kind-appropriate wall-clock deadline:

| Tool kind | Budget | Examples | |-----------|--------|----------| | Read | 30 s | get_node, list_children | | Write | 15 s | create_node, delete_node, edit_node | | Bulk | 180 s | insert_content, transaction, bulk_update, path_of, node_at_path | | Walk | 20 s (internal) | search_nodes, get_subtree, find_node |

cancel_all interru

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dromologue
• Source: dromologue/workflowyMCP
• License: MIT

Install and usage instructions live in the source repository linked above.