WorkFlowy

You run a dedicated MCP server that connects WorkFlowy outlines and tasks to your language model applications. It lets you create, update, list, and complete WorkFlowy nodes from any MCP-compatible client, enabling automated planning and task management within your AI workflows.

How to use

You interact with the WorkFlowy MCP server through an MCP client that supports standard JSON-RPC-like requests. The server exposes a set of tools to manage WorkFlowy nodes: create, update, retrieve, list children, delete, and toggle completion. Use hierarchical navigation starting from root-level nodes because there is no text search in this integration.

Typical usage patterns include creating a new node, adding child nodes under an existing parent, listing children to navigate the outline, updating node notes or layout, and marking items as completed. Always start from the root to locate the correct node IDs, since you cannot jump directly to deeply nested nodes using a single command.

Examples of common actions you can perform through the MCP client include creating a top-level project task list, adding a new todo under a parent node, marking a node as completed, listing all children of a given node, and updating a node’s notes. Remember that node IDs from the web interface are not compatible with API IDs, so you must rely on hierarchical navigation to reach the desired node.

How to install

Prerequisites: Python 3.10 or higher and a WorkFlowy account with API access. You also need a client capable of running MCP commands (such as Claude Desktop or another local MCP client).

Option 1: Install from PyPI (recommended)

# Install the package
pip install workflowy-mcp

Option 2: Quick Setup Script (macOS/Linux)

# Download and run the setup script
curl -sSL https://raw.githubusercontent.com/yourusername/workflowy-mcp/main/install.sh | bash

Option 2 alternative (Windows)

# Install via PowerShell (example)
irm https://raw.githubusercontent.com/yourusername/workflowy-mcp/main/install.ps1 | iex

Configuration

Configure your client to connect to the WorkFlowy MCP server. You will set up a local MCP server configuration so your client can start and communicate with the service.

The configuration below is the example you would place in your client’s MCP settings to start the WorkFlowy MCP server using a local runtime. This configuration enables the client to spawn the Python module that exposes the MCP endpoints.

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

Available tools

workflowy_create_node

Create a new node with a name, optional notes, and a chosen layout mode.

workflowy_update_node

Update properties of an existing node such as name, notes, layout, or completion state.

workflowy_get_node

Retrieve a specific node by its ID.

workflowy_list_nodes

List child nodes under a given parent node to navigate the outline.

workflowy_delete_node

Delete a node along with all its descendant nodes.

workflowy_complete_node

Mark a node as completed.

workflowy_uncomplete_node

Unmark a node as completed.