Skip to main content
Glama

WorkFlowy MCP Server

by vladzima
GitHub
Python
MIT License
1
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

  1. Get your WorkFlowy 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:

    { "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

Acknowledgments

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Enables interaction with WorkFlowy's outline and task management system through 8 comprehensive tools. Supports creating, updating, searching, and managing hierarchical nodes and tasks with high-performance async operations.

  1. MCP Tools Available
    1. ⚠️ Important Limitations
      1. Quick Start
        1. Prerequisites
        2. Installation
        3. Configuration
      2. Usage
        1. Working with New Nodes
        2. Navigating Existing Nodes
      3. Development
        1. Setup Development Environment
        2. Project Structure
        3. Running Tests
      4. API Reference
        1. Node Structure
        2. Error Handling
      5. Performance
        1. Contributing
          1. License
            1. Support
              1. Acknowledgments

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/vladzima/workflowy-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server