mcp-excalidraw-server: a live Excalidraw canvas for coding agents

The gap this fills: agents that draw blind

Most diagram generation is one-shot. A prompt goes in, a rendered image comes out, and the model never learns whether a label overflowed its box or an arrow crossed three other shapes. The README frames the project as the opposite of that: an agent draws, then looks. The canvas is a real Excalidraw instance, and the agent can query it as structured text through describe or as an image through screenshot, then adjust individual elements.

The intended user is a coding agent, not a chat user. The README names Claude Code, Codex CLI, Cursor and OpenCode as the recommended path, and the positioning is explicit: diagrams become repository artifacts. The exported .excalidraw file sits next to the code and gets updated when the code changes. That is a different job from a widget that streams a cat drawing into a conversation.

Two processes, one canvas: how the pieces connect

The architecture is two processes. A canvas server runs the Excalidraw web UI, a REST API and WebSocket real-time sync, listening on http://127.0.0.1:3000 by default. On top of that sits a thin front end, and you choose which one: the CLI, an MCP stdio server, or raw HTTP for LangChain and custom frameworks. All three drive the same canvas.

Since v1.1 the canvas server starts itself. Canvas-driving CLI commands and the MCP server on launch both auto-spawn it if nothing is listening. The status command is the exception: it only inspects current server state. Setting EXCALIDRAW_NO_AUTOSTART=1 turns the auto-spawn off, which matters in containers where no frontend build exists.

The MCP surface is 26 tools over stdio. The README states the server speaks MCP revision 2026-07-28, with server/discover, per-request _meta envelopes and tool calls that need no handshake, while remaining compatible with 2025-era clients that open with initialize. That dual path is the most interesting protocol decision in the project: new clients get statelessness, old configs keep working untouched.

Install and draw your first element from the CLI

The README recommends the agent skill plus CLI path for coding agents, invoked through npx with no configuration. The package name is mcp-excalidraw-server, and the CLI auto-starts the canvas when a command needs it. The README gives this as the invocation form for the CLI:

npx -y mcp-excalidraw-server <command>

Because status only inspects state, it will not start anything. If no canvas is running you should see a report that nothing is listening on the default port rather than a spawned server.

To drive the canvas, run a drawing command. The README describes the CLI as JSON in, JSON out and composable, so the shape of a call is a command plus a JSON payload. The exact command names and payload keys are listed in the CLI Reference section of the README, which is where you should confirm them rather than guessing.

With the canvas auto-started, the element should appear in the browser UI at http://127.0.0.1:3000, and the command should return a JSON result describing the created element.

For Claude Desktop and similar clients, the repository ships claude_desktop_config.json, so the fastest route is to copy that file rather than hand-write a server entry. Core drawing runs fully local with no API keys. Mermaid conversion happens in the local browser canvas. Only the share command is optional and uploads an encrypted scene to excalidraw.com.

What the element-level model buys you, and what it costs

The comparison table in the README is the clearest statement of intent. The official Excalidraw MCP is described as prompt in, diagram out, with state held as checkpoints inside the chat widget, no model-facing file export, and no layout tools. This project offers per-element create, read, update and delete, align, distribute, group and ungroup, lock and duplicate, named server-side snapshots, set_viewport for zoom-to-fit or centering, and .excalidraw export and import.

That is more control and more surface area. Twenty-six tools is a lot of context for a model to hold, and the failure mode is predictable: an agent that does not call describe or screenshot before editing will happily stack elements on top of each other. The project's own answer is the look-then-adjust loop, which only works if the agent actually looks. Nothing in the README enforces that.

The export work in v2.0 is the part worth taking seriously for anyone committing diagrams. Exports contain real Excalidraw elements, with shape and arrow labels as bound text and live arrow bindings, so files open correctly on excalidraw.com and in the Obsidian Excalidraw plugin instead of losing labels. Exports are byte-stable: deterministic ids, seeds and key order, so re-exporting an unchanged scene is byte-identical. For a repo where diagrams sit beside source, phantom diffs are a real annoyance, and this addresses it directly.

Node 20, Docker, and a canvas that will not start in the wrong image

The v2.0 release line is marked breaking for one reason: Node 20 is now the floor, up from 18, because the MCP TypeScript SDK v2 sets it. Everything else is described as backward compatible, including existing MCP client configs. If your toolchain is pinned to Node 18, this is the version boundary that stops you.

The Dockerfile shows a deliberate split. It builds the MCP server only, runs as a non-root nodejs user, and sets EXCALIDRAW_NO_AUTOSTART=1 with an explicit comment: the image has no frontend build, so auto-starting a canvas there would serve a blank UI. The canvas is its own service. The docker-compose.yml reflects that, with a canvas service on port 3000, a healthcheck against /health, and an mcp service behind the full profile that depends on canvas being healthy and points at it with EXPRESS_SERVER_URL=http://canvas:3000. The compose file's own usage note says running the mcp service requires a canvas running elsewhere, or the full profile for both.

One limitation the README states plainly: the canvas binds to 127.0.0.1 by default. That is a sensible default for a local drawing tool, and it also means remote or shared-canvas setups need the host binding changed deliberately rather than by accident.

When the official Excalidraw MCP is the better pick

The honest alternative is the official Excalidraw MCP, and the difference is not quality but shape. It is a chat widget: one prompt in, a diagram streamed inline, with two tools exposed to the model, a format reference and create_view. If you want to type "draw me a cat" in Claude or ChatGPT and see a picture, that is the shorter path, and it has no canvas server to run, no port to free, and no Node version to check.

Choose this project instead when the diagram has to survive. Persistent canvas with real-time sync, element-level edits, named snapshots for rollback, and file export mean the artifact can be reviewed, committed and regenerated. Multi-agent work on one canvas is also supported here and not in the single-chat widget. The trade is operational: you run a process, you keep a port open, and you accept that the model can now make twenty-six kinds of change to your scene.

Licence, maintenance and the upgrade bill

The project is MIT licensed, and the README states core drawing runs fully local with no API keys. Nothing in the licence restricts commercial use, but the dependency chain is worth a look before adopting: the canvas pulls in React, Express, ws, mermaid and the Excalidraw packages, so your licence and security review covers those too. This is not legal advice; read the licences yourself.

On maintenance, the last push was on 2026-09-08, and the repository is not archived. The README includes a Known Issues / TODO section and a Troubleshooting section, which is a reasonable sign that problems are tracked in the open rather than only in issues.

The upgrade cost is concentrated in v2.0. The Node floor moved to 20, which is a CI change as much as a runtime change. In exchange, existing MCP client configs keep working, and the export format changed in a way that matters if you already commit .excalidraw files: older exports that lost labels or were re-saved empty by the Obsidian plugin will now produce real elements, which means your next export may be a large diff even though the drawing did not change.

Editorial conclusion

Adopt it if your agent writes code and you want diagrams committed next to that code, with a canvas the model can inspect and correct. Skip it if you only want a picture inside a chat window, or if you are pinned to Node 18, since v2.0 raised the floor to Node 20. Before wiring it into a client, run the CLI status command against a local canvas, confirm port 3000 is free, and check whether your client speaks the 2026-07-28 MCP revision or still opens with initialize.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. yctimlin/mcp_excalidraw on GitHub