Workflowy MCP

What is Workflowy MCP about?

Workflowy MCP offers a server that connects AI models to a user's Workflowy account. Through defined tools, the server lets assistants retrieve node hierarchies, search text, add new items, edit existing entries, and mark tasks as complete or incomplete.

How to use Workflowy MCP?

1. Install – either globally with npm install -g mcp-workflowy or on‑the‑fly with npx mcp-workflowy server start.
2. Configure – create a .env file containing WORKFLOWY_USERNAME and WORKFLOWY_PASSWORD, or export those variables before starting the server.
3. Start – run npx mcp-workflowy server start (or the global command) to launch the MCP endpoint.
4. Connect – point your AI assistant or tooling to the server's address; the assistant can now invoke the provided tools.

Key Features

• Workflowy Integration – authenticates with username/password and operates on the user's account.
• MCP Compatibility – exposes a standard set of tools that any MCP‑aware AI can call.
• Node Operations – list nodes, search nodes, create nodes, update node text/description, toggle completion status.
• One‑Click VS Code Launch – badge link provides an instant NPX start inside VS Code.

Use Cases

• Quickly retrieve all notes for a specific project stored in Workflowy.
• Automate task completion by having an assistant mark finished items as completed.
• Generate next‑step suggestions by analyzing milestones and open tasks in Workflowy.
• Keep code documentation synchronized by letting an assistant create or update reference nodes.

FAQ

Q: Do I need a paid Workflowy plan? A: No, any Workflowy account with username/password access works.

Q: Which Node.js version is required? A: Node v18 or higher.

Q: Can I run the server locally without installing globally? A: Yes, using the NPX command shown above.

Q: How are credentials protected? A: Store them in a .env file or pass them as environment variables; the server never writes them to disk.

Q: What if I need to change credentials after the server is running? A: Stop the server, update the env variables, and restart.

Workflowy MCP

A Model Context Protocol (MCP) server for interacting with Workflowy. This server provides an MCP-compatible interface to Workflowy, allowing AI assistants to interact with your Workflowy lists programmatically.

What is MCP?

The Model Context Protocol (MCP) is a standardized way for AI models to interact with external tools and APIs. This server implements MCP to allow AI assistants (like ChatGPT) to read and manipulate your Workflowy lists through a set of defined tools.

Features

• Workflowy Integration: Connect to your Workflowy account using username/password authentication
• MCP Compatibility: Full support for the Model Context Protocol
• Tool Operations: Search, create, update, and mark nodes as complete/incomplete in your Workflowy

Example Usage:

Personally, I use workflowy as my project management tool. Giving my agent access to my notes, and my code base, the following are useful prompts:

• "Show my all my notes on project XYZ in workflowy"
• "Review the codebase, mark all completed notes as completed"
• "Given my milestones on workflowy for this project, suggest what my next task should be"

Installation

Prerequisites

• Node.js v18 or higher
• A Workflowy account

Quick Install

# Install the package globally
npm install -g mcp-workflowy

# Or use npx to run it directly
npx mcp-workflowy server start

Configuration

Create a .env file in your project directory with the following content:

WORKFLOWY_USERNAME=your_username_here
WORKFLOWY_PASSWORD=your_password_here

Alternatively, you can provide these credentials as environment variables when running the server.

Usage

Starting the Server

# If installed globally
mcp-workflowy server start

# Using npx
npx mcp-workflowy server start

Available Tools

This MCP server provides the following tools to interact with your Workflowy:

1. list_nodes - Get a list of nodes from your Workflowy (root nodes or children of a specified node)
2. search_nodes - Search for nodes by query text
3. create_node - Create a new node in your Workflowy
4. update_node - Modify an existing node's text or description
5. toggle_complete - Mark a node as complete or incomplete

Integrating with AI Assistants

To use this MCP server with AI assistants (like ChatGPT):

1. Start the MCP server as described above
2. Connect your AI assistant to the MCP server (refer to your AI assistant's documentation)
3. The AI assistant will now be able to read and manipulate your Workflowy lists

One-Click

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.