Skip to main content
Glama

WorkFlowy MCP Server

by vladzima
OverviewInspectSchemaRelated ServersScoreDiscussions
Python
Remote
MIT License
3

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
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

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