flowpocus MCP server
Commit Nov 8, 2026Enables AI agents to collaboratively edit real-time canvases alongside humans using typed server-owned commands.
Also known as SweetRetry/flowpocus
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 8, 2026
- License
- MIT
What is flowpocus MCP?
flowpocus enables AI agents to collaboratively edit real-time canvases alongside humans using typed server-owned commands.
Summary generated from the project's README
About flowpocus MCP server
Flowpocus provides a real-time collaborative canvas designed for simultaneous editing by humans and AI agents. While people interact through a web browser, agents connect via an MCP endpoint, a local CLI, or HTTP. The system uses React Flow for the editor interface and Yjs for conflict-free synchronization, ensuring that multiple users can work on the same canvas without data collisions.
Developers can integrate this server into their workflows by adding the stateless Streamable HTTP MCP endpoint to clients like Claude. The backend manages all canvas operations through typed, server-owned commands, which ensures consistency across all connection types. The architecture supports horizontal scaling through either a PostgreSQL database lease system or Redis Pub/Sub mode. It includes support for various node types such as text, image, and video, while providing independent undo and redo histories for every individual user.
What you can do with it
- 1Agentic Canvas ManagementAn AI client can retrieve a list of available canvases to determine where to perform work.
- 2Real-time Presence MonitoringUsers can observe the live movements and selections of other collaborators on the board.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
NEXT_PUBLIC_WS_URL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesweetretry/flowpocus is public and reachablegithub.com/sweetretry/flowpocus ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/sweetretry/flowpocus ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFlowpocus
Real-time collaborative canvas that humans and AI agents edit together. People work in the browser; agents connect through an MCP server, a CLI, or HTTP, and every change goes through the same typed, server-owned canvas commands. Built on React Flow, Yjs, and Hocuspocus.
Features
- Real-time Collaboration - Multiple users can edit the same canvas simultaneously
- Conflict-free Sync - Powered by Yjs CRDT for seamless concurrent editing
- User Presence - See other users' cursors and selections in real-time
- Scoped Undo/Redo - Each user has independent undo history
- Node Types - Text, image, and video nodes
- Agent Access - Typed server-owned commands over HTTP, a local CLI, and an MCP endpoint
- Horizontal Scaling - Each canvas lives on one owner instance behind a database lease, with fenced writes; Redis Pub/Sub is available as an alternative mode
- Light and Dark Themes - Follows the system color scheme, canvas controls included
Tech Stack
| Layer | Technology |
|---|---|
| Node Editor | React Flow |
| Real-time Sync | Yjs + Hocuspocus |
| Frontend | Next.js 16 + React 19 |
| Backend | Hono on Node.js |
| Database | PostgreSQL (node-postgres) + Drizzle ORM |
| UI Components | shadcn/ui on Base UI |
| Styling | Tailwind CSS v4 |
| Build System | Turborepo, tsdown for the backend and CLI |
| Package Manager | pnpm |
Getting Started
Prerequisites
- Node.js >= 24 (see
.node-version) - pnpm 12 (pinned in
packageManager; Corepack or a recent pnpm picks it up) - PostgreSQL 16+ (
docker compose up -dstarts one with the default credentials)
Installation
# Clone the repository
git clone https://github.com/SweetRetry/flowpocus.git
cd flowpocus
# Install dependencies (also installs the Lefthook git hooks)
pnpm install
# Start PostgreSQL and apply the migrations
docker compose up -d
pnpm db:migrate
After changing packages/database/src/schema, run pnpm db:generate to write a new migration, then pnpm db:migrate.
Development
# Start all services (frontend + backend)
pnpm dev
# Or start individually
pnpm dev:web # Frontend at http://localhost:3000
pnpm dev:backend # Backend at http://localhost:3001
Open http://localhost:3000/canvas (redirects to the showcase canvas) or
http://localhost:3000/canvas/{any-id}. A canvas is created on first connect.
Production Build
# NEXT_PUBLIC_WS_URL is inlined at build time
NEXT_PUBLIC_WS_URL=wss://your-host/collaboration pnpm build
pnpm --filter @workspace/backend start # node dist/index.js
pnpm --filter web start # next start
Running Multiple Instances
Every instance can accept any canvas. By default (CLUSTER_MODE=owner) a canvas loads on exactly one
instance, which holds a lease in PostgreSQL; the others forward its WebSocket and command traffic to that
owner. Give each instance a unique INSTANCE_ID and an INSTANCE_URL its peers can reach:
PORT=3001 INSTANCE_ID=a INSTANCE_URL=http://10.0.0.5:3001 pnpm --filter @workspace/backend start
PORT=3001 INSTANCE_ID=b INSTANCE_URL=http://10.0.0.6:3001 pnpm --filter @workspace/backend start
Set CLUSTER_MODE=redis with REDIS_URL on every instance to sync copies over Redis instead. All instances
in a cluster must use the same mode. ADR 0001 explains the
trade-off and when to switch.
Environment Variables
| Variable | Used by | Default |
|---|---|---|
PORT |
backend | 3001 |
DATABASE_URL |
backend, db:* scripts, tests |
postgres://flowpocus:flowpocus@localhost:5432/flowpocus |
CLUSTER_MODE |
backend, owner or redis (see docs/adr/0001-single-owner-placement.md) |
owner |
REDIS_URL |
backend, required when CLUSTER_MODE=redis |
unset |
INSTANCE_ID |
backend, lease owner and Redis node identity | random UUID |
INSTANCE_URL |
backend, address other instances forward to | http://localhost:$PORT |
LOG_LEVEL |
backend (debug, info, warn, error) |
info |
NEXT_PUBLIC_WS_URL |
web, at build time | ws://localhost:3001/collaboration |
FLOWPOCUS_SERVER_URL |
CLI | http://localhost:3001 |
Agent Access
Canvas Command contracts live in packages/commands; execution lives only in the backend.
The CLI and the MCP endpoint are transports for the same server commands.
Local CLI
# Create a target canvas
pnpm dev:cli canvases create --name "Agent Canvas"
# Discover commands and their JSON Schema from the server
pnpm dev:cli commands list
# Create a node; retry with the same command ID if the outcome is unknown
pnpm dev:cli commands execute create_node \
--canvas-id <canvasId> \
--command-id <stable-command-id> \
--input '{"type":"text","position":{"x":120,"y":80},"content":"Agent note"}'
MCP
The backend serves a stateless Streamable HTTP MCP endpoint at /mcp with list_canvases,
get_canvas, and one tool per canvas command:
claude mcp add --transport http flowpocus http://localhost:3001/mcp
Project Structure
flowpocus/
├── apps/
│ ├── web/ # Next.js frontend
│ ├── backend/ # Hono + Hocuspocus + server-owned commands + MCP
│ └── cli/ # Agent-facing server API client
├── packages/
│ ├── commands/ # Shared Zod command contracts
│ ├── canvas/ # React Flow nodes, plugins & hooks
│ ├── ui/ # shadcn/ui components and theme tokens
│ ├── database/ # Drizzle ORM + PostgreSQL
│ └── typescript-config/ # Shared TypeScript configs
├── docs/ # Design notes
└── ...
Scripts
| Command | Description |
|---|---|
pnpm dev |
Start development servers |
pnpm build |
Build all packages |
pnpm test |
Run tests |
pnpm typecheck |
Run TypeScript type checking |
pnpm lint |
Run Biome checks |
pnpm check |
Run Biome with auto-fix |
pnpm knip |
Find unused files, exports, and dependencies |
pnpm dev:cli <args> |
Call server-owned commands from the local CLI |
pnpm db:generate |
Write a migration from schema changes |
pnpm db:migrate |
Apply pending migrations |
pnpm db:studio |
Open Drizzle Studio |
Documentation
- ARCHITECTURE.md covers the data flow, sync, undo, and persistence in detail (Chinese).
- docs/adr records architecture decisions, starting with single-owner placement.
- docs/future holds open design questions, such as where to store Yjs snapshots.
- docs/retrospectives holds dated write-ups. The October 2026 retrospective (Chinese) walks through this round of changes, including how multi-instance sync moved from Redis broadcast to leases with fenced writes, and the bugs found on the way.
Contributing
Contributions are welcome! See CONTRIBUTING.md for setup, commit conventions, and the checks CI runs.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m "feat: add amazing feature") - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
MIT License - see LICENSE for details.
flowpocus MCP questions
How can I connect an AI agent to the canvas?
Agents can connect through an MCP server, a CLI, or via HTTP using typed server-owned canvas commands.
Does the canvas support multiple users editing at once?
Yes, it features real-time collaboration allowing multiple users to edit the same canvas simultaneously with conflict-free sync.
What technologies are used for real-time synchronization?
The system is powered by Yjs CRDT and Hocuspocus for seamless concurrent editing.