WorkFlowy MCP server
Lets an AI client search, read, create, update, move, and bulk-replace nodes in a WorkFlowy outline, and run usage reports.
Also known as mholzen/workflowy
- Stars
- 73
- Tools
- 18
- Downloads, 30 days
- —
- Latest version
- 0.8.1
- Last commit
- Aug 14, 2026
- License
- MIT
What is WorkFlowy MCP?
WorkFlowy lets an AI client search, read, create, update, move, and bulk-replace nodes in a WorkFlowy outline, and run usage reports. It exposes 18 tools, such as workflowy_get, workflowy_list, workflowy_search.
Summary generated from the project's README
About WorkFlowy MCP server
Managing and analyzing your Workflowy outlines through an AI assistant is possible with this tool. It allows developers and organizers to connect clients like Claude Desktop or Claude Code to their outline data to perform complex tasks such as searching with regex, bulk replacing text, and moving nodes. The server functions as both a command line interface and an MCP server, providing a way to interact with your data via terminal scripts or AI-driven conversations.
Users can perform standard CRUD operations like creating, updating, or deleting nodes, as well as advanced content transformations such as splitting text into child nodes or cleaning punctuation. The tool also provides analytical capabilities through usage reports that identify stale nodes, large subtrees, or frequently mirrored items. Setup requires a Workflowy API key stored in a local configuration file. For those needing to work without an internet connection, the server supports an offline mode using Dropbox backup files.
What you can do with it
- 1Clean up stale outline contentAsk your AI assistant to identify and list nodes that have not been modified for a long period.
- 2Perform bulk text updatesInstruct the client to find a specific string and replace it across your entire outline using regular expressions.
- 3Analyze outline structureRequest a report to see which parts of your outline contain the most content or have the highest number of children.
- 4Transform node contentTell the AI to take a single node containing a list and split it into multiple child nodes.
Written from the project's README. Every use case is checked against a quote from it.
How to install WorkFlowy MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall WorkFlowy MCP in Claude Code
$ claude mcp add --env 'WORKFLOWY_API_KEY=<YOUR_WORKFLOWY_API_KEY>' workflowy -- docker run -i --rm ghcr.io/mholzen/workflowy:0.8.1Install WorkFlowy MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"workflowy": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/mholzen/workflowy:0.8.1"
],
"env": {
"WORKFLOWY_API_KEY": "<YOUR_WORKFLOWY_API_KEY>"
}
}
}
}Install WorkFlowy MCP in VS Code
.vscode/mcp.json
{
"servers": {
"workflowy": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/mholzen/workflowy:0.8.1"
],
"env": {
"WORKFLOWY_API_KEY": "<YOUR_WORKFLOWY_API_KEY>"
}
}
}
}Install WorkFlowy MCP in VS Code CLI
$ code --add-mcp '{"name":"workflowy","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/mholzen/workflowy:0.8.1"],"env":{"WORKFLOWY_API_KEY":"<YOUR_WORKFLOWY_API_KEY>"}}'Install WorkFlowy MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"workflowy": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/mholzen/workflowy:0.8.1"
],
"env": {
"WORKFLOWY_API_KEY": "<YOUR_WORKFLOWY_API_KEY>"
}
}
}
}Install WorkFlowy MCP in Codex
$ codex mcp add workflowy --env 'WORKFLOWY_API_KEY=<YOUR_WORKFLOWY_API_KEY>' -- docker run -i --rm ghcr.io/mholzen/workflowy:0.8.1Install WorkFlowy MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.workflowy] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/mholzen/workflowy:0.8.1"] [mcp_servers.workflowy.env] WORKFLOWY_API_KEY = "<YOUR_WORKFLOWY_API_KEY>"
Install WorkFlowy MCP in Gemini CLI
$ gemini mcp add -s user -e 'WORKFLOWY_API_KEY=<YOUR_WORKFLOWY_API_KEY>' workflowy docker -- run -i --rm ghcr.io/mholzen/workflowy:0.8.1Install WorkFlowy MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"workflowy": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/mholzen/workflowy:0.8.1"
],
"env": {
"WORKFLOWY_API_KEY": "<YOUR_WORKFLOWY_API_KEY>"
}
}
}
}WorkFlowy MCP tools 18
Detected from the READMEworkflowy_getworkflowy_listworkflowy_searchworkflowy_targetsworkflowy_idworkflowy_report_countworkflowy_report_childrenworkflowy_report_createdworkflowy_report_modifiedworkflowy_report_mirrorsworkflowy_createworkflowy_update
Show all 18 toolsShow fewer tools
workflowy_moveworkflowy_deleteworkflowy_completeworkflowy_uncompleteworkflowy_replaceworkflowy_transform
Configuration
WORKFLOWY_API_KEYRequiredSecretYour Workflowy API key (get it from https://workflowy.com/api-key/)
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemholzen/workflowy is public and reachablegithub.com/mholzen/workflowy ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-14github.com/mholzen/workflowy ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model18 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWorkflowy MCP Server & CLI
A feature-rich Model Context Protocol (MCP) server and Command Line Interface (CLI) for Workflowy written in Go. Connect your AI assistant (Claude, ChatGPT, etc.) to your Workflowy data or run commands from a terminal emulator or script, including search, bulk replace, usage reports, and offline access capabilities.
Why This Workflowy MCP Server?
- Full-text search with regex
- Bulk search & replace
- Content transformation (split, clean, pipe to LLMs)
- Usage reports (stale nodes, size analysis, mirrors)
- Sandboxed AI access with
--write-root-id - Offline mode via backup files
- CLI + MCP server in one tool
- Caching for performance
- Homebrew installation
- Basic CRUD operations
- Using short IDs (Copy Internal Link)
Quick Start
Install via Homebrew
brew install mholzen/workflowy/workflowy-cli
Configure Your API Key
mkdir -p ~/.workflowy
echo "your-api-key-here" > ~/.workflowy/api.key
Get your API key at https://workflowy.com/api-key/
Run Your First Command
# Get the top-level nodes, and nodes two levels deep
workflowy get
# Generate a report showing where most of your nodes are
workflowy report count | pbcopy # paste directly into Workflowy!
Use pbcopy on macOS, clip on Windows, wl-copy on Linux, or xclip for X11 systems.
Use with Claude Desktop or Claude Code
Claude Code
claude mcp add --transport=stdio workflowy -- workflowy mcp --expose=all
Remove —expose=all to limit to read-only tools.
Claude Desktop
Add to your configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"workflowy": {
"command": "workflowy",
"args": ["mcp", "--expose=all"]
}
}
}
Restart Claude Desktop and start asking Claude to work with your Workflowy!
MCP Tools for AI Assistants
Read Tools (Safe)
| Tool | Description |
|---|---|
workflowy_get |
Get a node and its descendants as a tree |
workflowy_list |
List descendants as a flat list |
workflowy_search |
Search nodes by text or regex |
workflowy_targets |
List shortcuts and system targets (inbox, etc.) |
workflowy_id |
Resolve short ID or target key to full UUID |
workflowy_report_count |
Find where most of your content lives |
workflowy_report_children |
Find nodes with many children |
workflowy_report_created |
Find oldest nodes |
workflowy_report_modified |
Find stale, unmodified nodes |
workflowy_report_mirrors |
Find most mirrored nodes (requires backup) |
Write Tools
| Tool | Description |
|---|---|
workflowy_create |
Create new nodes |
workflowy_update |
Update node content |
workflowy_move |
Move node to a new parent |
workflowy_delete |
Delete nodes |
workflowy_complete |
Mark nodes complete |
workflowy_uncomplete |
Mark nodes incomplete |
workflowy_replace |
Bulk find-and-replace with regex |
workflowy_transform |
Transform node content (split, trim, shell commands) |
CLI Features
Search Your Entire Outline
# Find all TODOs (case-insensitive)
workflowy search -i "foobar"
# Regex search for dates
workflowy search -E "<time.*>"
# Search within a specific subtree (using Internal Link)
workflowy search "bug" --item-id https://workflowy.com/#/1bdae4aecf00
Bulk Search and Replace
# Preview changes first (dry run)
workflowy replace --dry-run "foo" "bar"
# Interactive confirmation
workflowy replace --interactive "foo" "bar"
# Use regex capture groups
workflowy replace "TASK-([0-9]+)" 'ISSUE-$1'
Some Common CRUD Operations
# Add a task to your inbox
workflowy create "Buy groceries" --parent-id=inbox
# Change the name of an item
workflowy update xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --name "Project Plan v2"
# Move an item to a different parent
workflowy move <item-id> <new-parent-id>
# Mark a node as complete, using a short ID
workflowy complete https://workflowy.com/#/xxxxxxxxxxxx
# Resolve a short ID or target key to full UUID
workflowy id inbox
Transform Content
# Split a node's content by newlines into child nodes
workflowy transform <item-id> split -s "\n"
# Clean up text
workflowy transform <item-id> trim
workflowy transform <item-id> no-punctuation
# Pipe content through any shell command (e.g., an LLM)
workflowy transform <item-id> -x 'echo {} | llm "summarize this"'
Usage Reports
# Where is most of my content?
workflowy report count --threshold 0.01
# Which nodes have the most children?
workflowy report children --top-n 20
# Find stale content (oldest modified)
workflowy report modified --top-n 50
# Find most mirrored nodes (requires backup)
workflowy report mirrors --top-n 20
Data Access Methods
Choose the best method for your use case:
| Method | Speed | Freshness | Offline | Best For |
|---|---|---|---|---|
--method=get |
Medium | Real-time | No | Specific items |
--method=export |
Fast* | 1 min worst case (due to rate limiting) | No | Full tree access |
--method=backup |
Fastest | Stale | Yes | Bulk operations |
*Cached after first fetch
Offline Mode with Dropbox Backup
Enable Workflowy's Dropbox backup and access your data offline:
workflowy get --method=backup
workflowy search -i "project" --method=backup
Installation Options
Homebrew (macOS & Linux)
brew install mholzen/workflowy/workflowy-cli
Scoop (Windows)
scoop bucket add workflowy https://github.com/mholzen/scoop-workflowy
scoop install workflowy
Go Install
go install github.com/mholzen/workflowy/cmd/workflowy@latest
Download Binary
Download pre-built binaries from GitHub Releases.
Docker
docker run --rm -e WORKFLOWY_API_KEY=your-key ghcr.io/mholzen/workflowy:latest get
From Source
git clone https://github.com/mholzen/workflowy.git
cd workflowy
go build ./cmd/workflowy
Documentation
Examples
AI Assistant Workflows
Ask Claude:
- "Search my Workflowy for all items containing 'meeting notes'"
- "Show me nodes I haven't touched in 6 months"
- "Replace all 'v1' with 'v2' in my Project A folder"
- "What's taking up the most space in my outline?"
- "Which nodes are mirrored the most?"
- "Move this item to my inbox"
CLI Workflows
# Morning review: find stale items
workflowy report modified --top-n 20
# Weekly cleanup: find oversized nodes
workflowy report count --threshold 0.05
# Find unnecessary mirrors
workflowy report mirrors --top-n 20
# Bulk rename: update project prefix
workflowy replace "OLD-" "NEW-" --parent-id projects-folder-id
# Split pasted content into child nodes
workflowy transform <item-id> split -s "\n"
Contributing
Contributions welcome! See the Contributing Guide.
# Development setup
git clone https://github.com/mholzen/workflowy.git
cd workflowy
go test ./...
License
MIT — see LICENSE
Acknowledgments
- Thanks to Andrew Lisy for requesting a method to sandbox write commands
- Thanks to Craig P. Motlin for pointing out mirrors are defined in the backup files
WorkFlowy MCP questions
How do I add WorkFlowy MCP to Claude Code?
Run claude mcp add --env 'WORKFLOWY_API_KEY=<YOUR_WORKFLOWY_API_KEY>' workflowy -- docker run -i --rm ghcr.io/mholzen/workflowy:0.8.1 in your terminal. Add --scope user to make it available in every project.
How do I add WorkFlowy MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does WorkFlowy MCP provide?
It exposes 18 tools, including workflowy_get, workflowy_list, workflowy_search, workflowy_targets, workflowy_id.
How do I connect WorkFlowy to Claude Desktop?
Add a workflowy entry to claude_desktop_config.json with the command workflowy and args mcp --expose=all, then restart Claude Desktop.
How do I authenticate the WorkFlowy MCP server?
Create a WorkFlowy API key and save it to ~/.workflowy/api.key, or pass it via the WORKFLOWY_API_KEY environment variable.
Can I search my WorkFlowy outline with regex?
Yes, the search command supports case-insensitive and regex searches, optionally scoped to a subtree via an internal link ID.
Does it support bulk find-and-replace?
Yes, the replace command does regex-capable bulk replacement with dry-run and interactive confirmation options.
Can it work offline?
Yes, if WorkFlowy's Dropbox backup is enabled, use --method=backup to query a local backup without network access.