Workflowy MCP
A Model Context Protocol (MCP) server that integrates WorkFlowy's outline and task management capabilities with LLM applications.
Installation
npx workflowy-mcpAsk AI about Workflowy MCP
Powered by Claude Β· Grounded in docs
I know everything about Workflowy MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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_nodeswithout 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
mcpServerssection:{ "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" } } } } - Mac:
-
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
