Whiteboard MCP

Whiteboard MCP is a free, open-source Excalidraw whiteboard MCP server that runs locally, even offline. Your coding agent draws diagrams on a live board beside the chat, and sees what you draw back. Works with Claude Code, Codex, Cursor, Gemini CLI, VS Code, Windsurf, Devin and any other MCP client.

claude mcp add whiteboard --scope user -- npx -y @ansuman-shukla/whiteboard-mcp

_{Needs Node.js 20+. Using Codex, Cursor, Gemini CLI, VS Code or another agent? Commands for every agent ↓}

_{Playing Dots and Boxes with an agent: you draw a line, it sees your move and plays back.}

Features

What you can do with it

Understand an architecture

"How does a typical checkout backend work? Draw it on the whiteboard." The agent draws it piece by piece and highlights what it's explaining. You move a box, circle the part you're unsure about and leave a note. It reads exactly what you changed and answers on the board.

Explain a flow

"How does login work here?" Arrows stay attached as things move, and the agent answers your notes on its next look.

Make something

"Paint the Mona Lisa, then refine it with the pencil." Shapes, freehand strokes and frames, all editable.

More to try

• "Explain how a request flows through this repo, on the whiteboard."
• "Teach me how a TCP handshake works, step by step."
• "Draw our deploy pipeline and mark the single points of failure."
• "Compare option A and option B side by side on the board."
• "I circled something on the board, take a look."

Quick start

Add it to your agent

Needs Node.js 20+. Add it, then start a new chat:

# Claude Code
claude mcp add whiteboard --scope user -- npx -y @ansuman-shukla/whiteboard-mcp

# Codex CLI
codex mcp add whiteboard -- npx -y @ansuman-shukla/whiteboard-mcp

# Gemini CLI
gemini mcp add --scope user whiteboard npx -y @ansuman-shukla/whiteboard-mcp

# Devin CLI
devin mcp add whiteboard --scope user -- npx -y @ansuman-shukla/whiteboard-mcp

# VS Code
code --add-mcp '{"name":"whiteboard","command":"npx","args":["-y","@ansuman-shukla/whiteboard-mcp"]}'

Cursor, Claude Desktop, Windsurf and other JSON configs (~/.cursor/mcp.json, Claude Desktop's config, …):

{ "mcpServers": { "whiteboard": { "command": "npx", "args": ["-y", "@ansuman-shukla/whiteboard-mcp"] } } }

OpenCode (opencode.json):

{ "mcp": { "whiteboard": { "type": "local", "command": ["npx", "-y", "@ansuman-shukla/whiteboard-mcp"] } } }

Agents without MCP, project-level configs and more: client setup. For boards in a tab beside the chat, install the IDE panel. The bundled skill teaches the agent when a drawing helps.

Whiteboard MCP vs Excalidraw MCP

_{Want a quick one-off diagram inside Claude or ChatGPT on the web? Excalidraw MCP is great for that. Full comparison →}

FAQ

Is there an Excalidraw MCP server that runs locally and works offline?

Yes, that's Whiteboard MCP. It runs a small daemon on 127.0.0.1 and serves the Excalidraw viewer with its fonts bundled. After the first npx download it needs no internet, no account and no API key. Boards are plain JSON files in ~/.whiteboard-mcp.

How do I let Claude Code, Codex or Cursor draw diagrams?

Add the MCP server with the one-line command for your agent above, start a new chat and ask: "Draw how this repo handles a request on the whiteboard." The agent draws step by step on a live Excalidraw board beside the chat.

Can the agent see what I draw on the whiteboard?

Yes. Every time it looks, it gets a short list of what you added, moved or deleted, plus any notes you left. It can also take a PNG screenshot of the board to check its own layout.

Which agents and editors does it work with?

Any MCP client: Claude Code, Claude Desktop, OpenAI Codex, Cursor, Gemini CLI, VS Code (Copilot agent mode), Windsurf, Devin, OpenCode and more. Agents without MCP can use the plain whiteboard-mcp call CLI. The IDE panel shows boards in a tab beside the chat in VS Code, Cursor, Windsurf and Devin Desktop; anywhere else they open in your browser.

Can it turn Mermaid into an Excalidraw diagram, or export it?

Yes. canvas_mermaid converts Mermaid (flowcharts, sequence diagrams, …) into editable hand-drawn elements, and canvas_export saves the board as .excalidraw or .png in your project.

Are boards saved? Can I reopen one later?

Each chat gets its own board, saved on disk. Any later chat, even in another folder, can reopen it by name or find it by the text on it, and you can keep frozen copies in a saved library. See boards.

Is it free and private?

Yes. It's MIT licensed with no license key or paid tier. Everything stays on your machine: the daemon only listens on 127.0.0.1 and every API call needs a per-user token. See security.

Client setup · Boards · IDE panel · Tools & how it works · Configuration · Security · Contributing
MIT License · built on Excalidraw