Skip to main content
Glama

WorkFlowy MCP Server

by vladzima
GitHub
Python
MIT License
  • 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 like Claude Desktop.

Features

  • 8 MCP Tools for complete WorkFlowy node management
  • FastMCP Framework for reliable MCP implementation
  • High Performance with async operations and rate limiting
  • Automatic Retry with exponential backoff
  • Structured Logging for debugging and monitoring

MCP Tools Available

ToolDescription
workflowy_create_nodeCreate new nodes with name, notes, and priority
workflowy_update_nodeUpdate existing node properties
workflowy_get_nodeRetrieve a specific node by ID
workflowy_list_nodesList nodes with filtering and pagination
workflowy_delete_nodeDelete a node and its children
workflowy_complete_nodeMark a node as completed
workflowy_uncomplete_nodeMark a node as uncompleted
workflowy_search_nodesSearch nodes by text query

Quick Start

Prerequisites

  • Python 3.10 or higher
  • WorkFlowy account with API access
  • Claude Desktop or other MCP-compatible client

Installation

# 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 Claude Desktop or another 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_BASE_URL": "https://beta.workflowy.com/api", // "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:

"Create a new WorkFlowy node called 'Project Ideas' with high priority" "List all my uncompleted tasks" "Search for nodes containing 'meeting'" "Mark the node with ID abc123 as completed" "Update the 'Weekly Goals' node with new notes"

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", "nm": "Node name", "no": "Node notes/description", "cp": false, # Completed status "priority": 2, # 0-3 (0=none, 1=low, 2=normal, 3=high) "ch": [], # Child nodes "created": 1234567890, # Unix timestamp "modified": 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

This server cannot be installed

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

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. Features
    1. MCP Tools Available
      1. Quick Start
        1. Prerequisites
        2. Installation
        3. Configuration
      2. Usage
        1. Development
          1. Setup Development Environment
          2. Project Structure
          3. Running Tests
        2. API Reference
          1. Node Structure
          2. Error Handling
        3. 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