You can run a dedicated WorkFlowy MCP Server that exposes a set of MCP endpoints to manage WorkFlowy outlines and tasks from your language models or automation agents. This server lets you create, read, update, delete, and complete nodes in WorkFlowy through simple MCP calls, enabling seamless integration with your AI workflows.

How to use

You will run a local MCP server process that your agent can talk to using the MCP client. Start the server and point your client at the local endpoint, then perform operations like creating nodes, listing children, updating notes, and marking items as completed. Because this server translates MCP calls into WorkFlowy actions, your agent can build complex task hierarchies and workflows inside WorkFlowy without direct manual interaction.

How to install

Prerequisites you need before installing this MCP server are Python 3.10 or higher, a WorkFlowy account with API access, and a compatible MCP client such as Claude Desktop or another local MCP client.

Choose one of the installation options below and follow the steps exactly as written.

Option 1: Install from PyPI (Recommended)

pip install workflowy-mcp

Option 2: Quick setup script

curl -sSL https://raw.githubusercontent.com/yourusername/workflowy-mcp/main/install.sh | bash

On Windows you can use the PowerShell counterpart:

irm https://raw.githubusercontent.com/yourusername/workflowy-mcp/main/install.ps1 | iex

Option 3: Manual installation from source

Clone the repository to explore or customize

git clone https://github.com/vladzima/workflowy-mcp.git cd workflowy-mcp pip install -e .

## Configuration

Configure your MCP client to load the server as an MCP endpoint. The server is started as a local stdio service using Python, and you must provide your WorkFlowy API key and optional settings as environment variables.

Example client configuration for Claude Desktop or a similar MCP client shows how to register the stdio MCP server under the mcpServers section. Use the following JSON snippet as a guide and adapt to your environment.

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

## Notes and tips

Important limitations exist when using the WorkFlowy API from MCP. You can list root-level nodes and navigate down the tree by listing children, but you cannot search by name or content, and you cannot jump directly to deeply nested nodes. The web interface IDs are not compatible with API IDs, so you must traverse from root to locate your target nodes.

## Passing work with nodes

After you configure the server, you can perform common actions through your MCP client, such as creating new nodes, updating existing ones, listing children, and marking items as completed or uncompleted.

## Development and testing

If you contribute or test locally, set up a development environment and run tests to verify behavior. Use a virtual environment, install development dependencies, and run unit and integration tests as needed.

## 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, or layout.

### workflowy\_get\_node

Retrieve details for a specific node by its ID.

### workflowy\_list\_nodes

List child nodes under a specified parent node to navigate the hierarchy.

### workflowy\_delete\_node

Delete a node along with all of its descendant children.

### workflowy\_complete\_node

Mark a node as completed.

### workflowy\_uncomplete\_node

Unmark a node as completed.