Overview

This MCP (Model Context Protocol) server integrates Workflowy outlines with an MCP-compatible backend to enable real-time synchronization, secure backups, and multi-device collaboration. It acts as a middle layer between Workflowy clients and persistent storage, normalizing outline changes into MCP messages so clients can subscribe and reconcile state efficiently.

For developers, this server is useful when you need a stable synchronization endpoint for custom Workflowy integrations or multi-client editors. It provides endpoints and/or WebSocket feeds for incremental updates, tools for backups and restores, and configuration hooks for storage providers (local disk, S3, etc.), so teams can preserve outline history and enable collaborative workflows without relying solely on the Workflowy web UI.

Features

Real-time outline synchronization via MCP-compatible WebSocket and REST endpoints
Incremental change streaming for efficient client updates
Secure backups and restore tools (local and cloud storage options)
Authentication and token-based access control for clients
Simple configuration via environment variables and Docker
Optional CLI for snapshot export/import and manual maintenance
Lightweight: designed for small teams or personal deployment

Installation / Configuration

Clone the repository and run with Docker or Node.js. Example steps:

Clone the repo

git clone https://github.com/danield137/mcp-workflowy.git
cd mcp-workflowy

Using Docker Compose (recommended)

# copy example environment and edit values
cp .env.example .env

# start service and dependencies
docker-compose up -d

Run with Node.js (development)

# install dependencies
npm ci

# copy and edit environment variables
cp .env.example .env

# start
npm start

Common environment variables

Variable	Description	Example
PORT	Port the MCP server listens on	8080
MCP_JWT_SECRET	Secret for signing client tokens	supersecretkey
STORAGE_PATH	Local path for snapshots/backups	/var/lib/mcp-workflowy
S3_BUCKET	(optional) S3 bucket for backup storage	my-workflowy-backups
LOG_LEVEL	Logging verbosity (debug/info/warn/error)	info

Example .env snippet

PORT=8080
MCP_JWT_SECRET=replace_with_secure_value
STORAGE_PATH=./data
LOG_LEVEL=info

Available Resources

GitHub repository: https://github.com/danield137/mcp-workflowy — source, issues, and contribution guidance.
.env.example — template for required configuration variables.
Docker Compose file — quick deployment with a local volume for persistent storage.
API schema / Postman collection (if provided in repo) — importable resources for testing REST endpoints.
CLI utilities — snapshot export/import helpers (check scripts in package.json).

If the repository contains additional scripts, look in the scripts/ or tools/ directory for maintenance utilities (snapshot, migrate, restore).

Use Cases

Cross-device editing: Run the MCP server on a personal VPS and point multiple clients (desktop, mobile, browser extension) at the MCP endpoint so edits made on one device are reflected across all devices in near real-time.
Secure backup and history: Configure STORAGE_PATH or an S3_BUCKET to regularly persist snapshot files. Use the CLI to export daily backups and restore to a new server if needed.
Team collaboration: Host a central MCP server for a small team so multiple collaborators can subscribe to outlines and reconcile changes without requiring everyone to use the Workflowy UI directly.
Custom clients and integrations: Build bespoke editors, visualizers, or analysis tools that consume MCP messages from the server to render or transform Workflowy outlines, or to feed outline changes into other systems (e.g., task trackers, automated reports).

Quick API Examples

Obtain a client token (example)

POST /auth/token
Content-Type: application/json

{
  "client_id": "my-client",
  "secret": "client-secret"
}

Subscribe via WebSocket (pseudo-code)

const ws = new WebSocket('ws://localhost:8080/ws?token=YOUR_TOKEN');
ws.onmessage = (evt) => {
  const mcpMessage = JSON.parse(evt.data);
  // reconcile outline state
};

Trigger a backup (REST)

POST /backup
Authorization: Bearer <ADMIN_TOKEN>

Troubleshooting & Next Steps

Check logs (LOG_LEVEL) and ensure STORAGE_PATH is writable.
If using S3, verify credentials and region configuration.
For production, set a strong MCP_JWT_SECRET and run behind TLS (reverse proxy like Nginx).
Review the GitHub issues and README in the repository for repository-specific instructions, example clients, and upgrades.

This server provides a straightforward route to make Workflowy outlines available to MCP clients, enabling synchronization, durability, and integration points for building richer outline-driven workflows.

Workflowy MCP Server for Outline Sync