What can you do with this server?

The WorkFlowy MCP Server integrates WorkFlowy's outline and task management with LLM applications through CRUD operations on nodes. **Capabilities:** * **Create nodes**: Add new items with customizable name, notes, layout mode (bullets, todo, h1-h3), position (top/bottom), initial completion status, and parent hierarchy * **Update nodes**: Modify existing node properties including name, notes, layout mode, and completion status * **Retrieve nodes**: Fetch specific nodes by ID with all metadata (timestamps, completion status, layout) * **List nodes**: Navigate the hierarchy by listing root-level nodes or children of any parent node * **Delete nodes**: Remove nodes and all their children from the outline * **Manage completion**: Mark nodes as completed or uncompleted for task tracking workflows * **Error handling**: Receive consistent error responses with type, message, and context * **Performance configuration**: Optional rate limiting, retry logic, and timeout settings via environment variables **Important Limitations:** * **No search functionality**: Cannot search by name or content; must navigate hierarchically from root * **Hierarchical navigation only**: Must traverse the tree level-by-level to reach deeply nested nodes * **API ID incompatibility**: Web interface node IDs are NOT compatible with API IDs * **Limited discovery**: Requires multiple list operations starting from root to find specific nodes

Which integrations are available for this server?

Provides comprehensive WorkFlowy integration with 8 MCP tools for complete [outline](/mcp/servers/integrations/outline) and task management, including creating, updating, deleting, and searching nodes, as well as managing task completion status and priorities.

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