What can you do with this server?

The WorkFlowy MCP Server enables LLM applications to manage, navigate, and transform WorkFlowy outlines through comprehensive tools for node operations, advanced bulk transformations, and hierarchical exploration. Core Node Operations: Create, read, update, delete, move, complete/uncomplete, and export nodes with support for names, notes, layout modes (bullets/todo/h1/h2/h3), and hierarchical positioning. NEXUS System - Advanced Bulk Operations: * GLIMPSE - Instant WebSocket-based capture of expanded WorkFlowy views creating terrain and phantom gem files * Corinthian Workflow - Multi-stage process: coarse terrain mapping (scry), selective deepening (ignite shards), revelation (anchor gems/jewels), semantic transformations (JEWELSTORM operations: MOVE/DELETE/RENAME/CREATE, SET_NOTE/ATTRS, SEARCH_REPLACE with regex), and weaving changes back to WorkFlowy * Guided Exploration - Start, step through, resume, and finalize exploration sessions with DFS traversal modes and node labeling Loading & Export: Load entire trees via WebSocket (glimpse), API (scry), or hybrid methods with depth/size controls; export nodes with all children; convert between JSON and Markdown formats. ETCH Commands: Create multiple nodes from JSON structures synchronously or asynchronously for large operations. Job Management: Track status and cancel long-running async operations (ETCH, NEXUS WEAVE). Backup/Restore: Create, list, restore, and purge Keystone backups of node trees. Key Limitation: Must navigate hierarchically from root—the WorkFlowy API doesn't support direct search by name/content or jumping to deeply nested nodes. Web interface node IDs are incompatible with API IDs.

How do I use WorkFlowy MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@WorkFlowy MCP Server create a new task called 'Finish quarterly report' under my 'Work Projects' node" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

WorkFlowy MCP Server

A Model Context Protocol (MCP) server that integrates WorkFlowy's outline and task management capabilities with LLM applications.

MCP Tools Available

Tool	Description
`workflowy_create_node`	Create new nodes with name, notes, and layout mode
`workflowy_update_node`	Update existing node properties
`workflowy_get_node`	Retrieve a specific node by ID
`workflowy_list_nodes`	List child nodes of a specific parent
`workflowy_delete_node`	Delete a node and its children
`workflowy_complete_node`	Mark a node as completed
`workflowy_uncomplete_node`	Mark a node as uncompleted

⚠️ Important Limitations

The WorkFlowy API has significant discovery limitations:

✅ CAN list root-level nodes (call list_nodes without parent_id)
✅ CAN navigate down the tree by listing children of discovered nodes
❌ CANNOT search for nodes by name or content
❌ CANNOT jump directly to deeply nested nodes
❌ CANNOT use node IDs from WorkFlowy web URLs (they use different IDs)

Practical Impact:

You must navigate hierarchically from root to find existing nodes
No text search means manually traversing the tree to find specific content
Deep nodes require multiple list operations to reach
The web interface IDs (workflowy.com/#/abc123) are NOT compatible with API IDs

Quick Start

Prerequisites

Python 3.10 or higher
WorkFlowy account with API access
Claude Desktop or other (local, since it's a python package) MCP-compatible client

Installation

Option 1: Install from PyPI (Recommended)

# Install the package pip install workflowy-mcp

Option 2: Quick Setup Script

# Download and run the setup script curl -sSL https://raw.githubusercontent.com/yourusername/workflowy-mcp/main/install.sh | bash # Or on Windows: # irm https://raw.githubusercontent.com/yourusername/workflowy-mcp/main/install.ps1 | iex

Option 3: Manual Installation from Source

# Clone the repository (if you want to contribute or modify) git clone https://github.com/vladzima/workflowy-mcp.git cd workflowy-mcp pip install -e .

Configuration

Get your WorkFlowy API key:
- From WorkFlowy
Configure client: Edit your client configuration (Claude Desktop example):
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add to the mcpServers section:
{ "mcpServers": { "workflowy": { "command": "python3", "args": ["-m", "workflowy_mcp"], "env": { "WORKFLOWY_API_KEY": "your_actual_api_key_here", // Optional settings (uncomment to override defaults): // "WORKFLOWY_API_URL": "https://workflowy.com/api/v1", // "WORKFLOWY_REQUEST_TIMEOUT": "30", // "WORKFLOWY_MAX_RETRIES": "3", // "WORKFLOWY_RATE_LIMIT_REQUESTS": "60", // "WORKFLOWY_RATE_LIMIT_WINDOW": "60" } } } }
Restart your client to load the MCP server

Usage

Once configured, you can use WorkFlowy tools with your agent:

Working with New Nodes

"Create a new WorkFlowy node called 'Project Tasks'" # Returns: Created node with ID: abc-123-def "Create a todo item 'Review PR' under parent node abc-123-def" "Mark the node abc-123-def as completed" "List all children of node abc-123-def"

Navigating Existing Nodes

Since there's no search, you must navigate from root:

"List my root-level WorkFlowy nodes" # Returns: List of top-level nodes with their IDs "List children of node abc-123-def" # Navigate deeper into your outline "Get details for node abc-123-def" "Update node abc-123-def with new notes"

Note: The node IDs from the web interface URLs are NOT compatible with the API.

Development

Setup Development Environment

# Create virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install in development mode pip install -e ".[dev]" # Run tests pytest # Run with coverage pytest --cov=workflowy_mcp # Run linting ruff check src/ mypy src/ black src/ --check

Project Structure

workflowy-mcp/ ├── src/ │ └── workflowy_mcp/ │ ├── __init__.py │ ├── __main__.py # Entry point │ ├── server.py # FastMCP server & tools │ ├── config.py # Configuration │ ├── transport.py # STDIO transport │ ├── client/ │ │ ├── api_client.py # WorkFlowy API client │ │ ├── rate_limit.py # Rate limiting │ │ └── retry.py # Retry logic │ ├── models/ │ │ ├── node.py # Node models │ │ ├── requests.py # Request models │ │ ├── config.py # Config models │ │ └── errors.py # Error models │ └── middleware/ │ ├── errors.py # Error handling │ └── logging.py # Request logging ├── tests/ │ ├── contract/ # Contract tests │ ├── integration/ # Integration tests │ ├── unit/ # Unit tests │ └── performance/ # Performance tests ├── pyproject.toml # Project configuration ├── README.md # This file ├── CONTRIBUTING.md # Contribution guide ├── install.sh # Unix/Mac installer └── install.ps1 # Windows installer

Running Tests

# Run all tests pytest # Run specific test categories pytest tests/unit/ pytest tests/contract/ pytest tests/integration/ pytest tests/performance/ # Run with coverage report pytest --cov=workflowy_mcp --cov-report=html # Run with verbose output pytest -xvs

API Reference

Node Structure

{ "id": "unique-node-id", "name": "Node name", # Text content "note": "Node notes/description", # Optional notes "layoutMode": "bullets", # Display mode: bullets, todo, h1, h2, h3 "completedAt": null, # Completion timestamp (null if not completed) "children": [], # Child nodes array "createdAt": 1234567890, # Unix timestamp "modifiedAt": 1234567890 # Unix timestamp }

Error Handling

All tools return a consistent error format:

{ "success": false, "error": "error_type", "message": "Human-readable error message", "context": {...} // Additional error context }

Performance

Automatic rate limiting prevents API throttling
Token bucket algorithm for smooth request distribution
Adaptive rate limiting based on API responses
Connection pooling for efficient HTTP requests

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

MIT License - see LICENSE file for details.

Support

Acknowledgments

Built with FastMCP framework
Integrates with WorkFlowy API
Compatible with Claude Desktop and other MCP clients

WorkFlowy MCP Server

WorkFlowy MCP Server

MCP Tools Available

⚠️ Important Limitations

Quick Start

Prerequisites

Installation

Option 1: Install from PyPI (Recommended)

Option 2: Quick Setup Script

Option 3: Manual Installation from Source

Configuration

Usage

Working with New Nodes

Navigating Existing Nodes

Development

Setup Development Environment

Project Structure

Running Tests

API Reference

Node Structure

Error Handling

Performance

Contributing

License

Support

Acknowledgments

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API