WorkFlowy MCP Server

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

MCP Tools Available

⚠️ 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

1. Get your WorkFlowy API key:

   • From WorkFlowy

2. 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"
         }
       }
     }
   }
   

3. 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

• Report bugs
• Request features

Acknowledgments

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