WorkFlowy MCP Server

# 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) ```bash # Install the package pip install workflowy-mcp ``` #### Option 2: Quick Setup Script ```bash # 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 ```bash # 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](https://beta.workflowy.com/api-key) 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: ```json { "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 ```bash # 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 ```bash # 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 ```python { "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: ```json { "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](CONTRIBUTING.md) for development setup and contribution guidelines. ## License MIT License - see [LICENSE](LICENSE) file for details. ## Support - [Report bugs](https://github.com/vladzima/workflowy-mcp/issues) - [Request features](https://github.com/vladzima/workflowy-mcp/issues) ## Acknowledgments - Built with [FastMCP](https://github.com/jlowin/fastmcp) framework - Integrates with [WorkFlowy API](https://beta.workflowy.com/api-reference/) - Compatible with [Claude Desktop](https://claude.ai/desktop) and other MCP clients