mcp_excalidraw: a persistent canvas workbench for coding agents
MCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.
At a glance
- What is it?
- The project splits into a local canvas server and three thin clients (CLI, MCP stdio server, REST). It is aimed at agents that need to iterate on a diagram element by element, not at chat widgets that render one picture from one prompt.
- Who is it for?
- Adopt it if your agent already writes code into a repository and you want diagrams to sit next to that code as .excalidraw files that re-export byte-identically. Skip it if you only need a diagram rendered once inside a chat window, or if you cannot run Node 20 or newer and a local browser canvas.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is iteration, not drawing
Most diagram generation from a language model is a single shot. You describe an architecture, the model emits a picture, and if a label overlaps an arrow you start over with a new prompt. The README frames the gap directly: the agent should be able to query, screenshot, and update individual elements, and iterate until labels fit, nothing overlaps, and arrows route cleanly. That is a different requirement from producing a diagram. It requires the diagram to exist as addressable state that both the agent and a human can edit, and it requires the agent to be able to look at what it produced. The audience follows from that. This is for coding agents (the README names Claude Code, Codex CLI, Cursor and OpenCode) that operate inside a repository and are expected to leave artifacts behind. It is not for someone who wants a picture in a chat window.
Two processes, one canvas, three front ends
The architecture is stated plainly: a canvas server that hosts the Excalidraw web UI plus a REST API plus WebSocket real-time sync, listening on http://127.0.0.1:3000 by default, and a thin front end of your choice. The CLI, the MCP stdio server, and raw HTTP all drive the same canvas. That single-canvas design is what makes concurrent agents possible, and it is also what makes the tool stateful in a way most MCP servers are not. Since v1.1 the canvas server starts itself: canvas-driving CLI commands and the MCP server on launch auto-spawn it if nothing is listening. The status command only inspects current server state, so it will not start anything, and EXCALIDRAW_NO_AUTOSTART=1 opts out of the whole behaviour. The MCP surface is 26 tools over stdio. The README states the server speaks protocol revision 2026-07-28, with server/discover and per-request _meta envelopes so modern clients can call tools statelessly without an initialization handshake, while 2025-era clients that open with initialize keep working.
Getting it running: npx first, config files second
The recommended path for coding agents is the agent skill plus CLI, invoked as npx -y mcp-excalidraw-server <command>, described as zero config with the canvas auto-starting and composable JSON in and out. For MCP clients you configure the server instead. The README lists per-client setup for Claude Desktop, Claude Code, Cursor, Codex CLI, OpenCode and Antigravity, and it notes existing MCP client configs remain valid across the 2.0 upgrade. From source or Docker there is a separate quick start section. Two constraints matter before you install. Node 20 or newer is required as of v2.0, raised from 18 because the MCP TypeScript SDK v2 sets that floor; the README calls this the breaking change and says everything else is backward compatible. Core drawing is fully local and needs no API keys. Mermaid conversion runs in the local browser canvas, which means a browser is part of the runtime, not an optional extra. Only the share command uploads anything, and it sends an encrypted scene to excalidraw.com.
Why exports are the part worth checking
The v2.0 notes spend most of their length on export fidelity rather than on drawing. Exported .excalidraw and .excalidraw.md files now contain real Excalidraw elements, with shape and arrow labels as bound text and live arrow bindings, so they open correctly on excalidraw.com and in the Obsidian Excalidraw plugin instead of losing labels or being re-saved empty by the plugin. Exports are also byte-stable: deterministic ids, seeds, and key order mean re-exporting an unchanged scene is byte-identical, so committed diagrams do not produce phantom git diffs and Obsidian block references survive re-exports. There are two Obsidian fixes listed, one for Windows CRLF .excalidraw.md import and one extending ## Text Elements block references to cover shape labels. If you are going to commit diagrams next to source, this is the property that decides whether the tool is usable in a repo, and the README treats it as such.
Where it is the wrong tool
The README's own comparison makes the boundary clear. The official Excalidraw MCP is described as a chat widget that streams a diagram inline from a single prompt, where the model gets two tools: a format reference and create_view. If that is your use case, draw me a cat in Claude or ChatGPT, this project is heavier than you need. You would be running a local server, a browser canvas and a WebSocket sync layer to produce one image. The cost is real: a long-running process on port 3000, a Node 20 floor that will block anyone still on Node 18, and a browser dependency for Mermaid conversion. There is also a statefulness cost that the README does not discuss. A persistent shared canvas means two agents drawing at once can collide, and the material does not describe any locking or conflict resolution beyond naming multi-agent use as a feature. Treat concurrent editing as something to test in your own setup rather than something the documentation settles. The Known Issues / TODO section exists in the repository, but nothing from it was retrieved here, so I cannot tell you what the maintainers already know is broken.
Compared with the official Excalidraw MCP
The difference is not quality, it is shape. The official MCP is prompt in, diagram out, with checkpoints held inside the chat widget and declarative re-sends with delete markers as the only way to change anything. This project offers full create, read, update and delete per element, named server-side snapshots instead of widget checkpoints, and layout operations (align, distribute, group and ungroup, lock, duplicate) that have no counterpart there. The agent can see the canvas two ways: describe for structured text and screenshot for an image. It can set the viewport, either zoom-to-fit all or selected elements, center on one element, or manual zoom. It can export and import .excalidraw files, convert Mermaid, and produce shareable URLs. It also works without MCP at all, through the CLI, the agent skill or the REST API, which matters if your framework is LangChain rather than an MCP client. The official widget wins on one axis: nothing to install, nothing to keep running, no port to manage.
Upgrade and maintenance cost
The licence is MIT, which permits commercial use and modification, though the usual caveat applies: this is a description of the licence identifier, not legal advice, and you should read the LICENSE file yourself. The package is published to npm as mcp-excalidraw-server, so upgrades arrive through the normal Node toolchain. The v2.0 release is the one to plan around. The Node floor moved from 18 to 20 because of the MCP TypeScript SDK v2, and the README states the rest is backward compatible, including existing MCP client configs. That is an unusually clean upgrade story, but it depends on your runtime being current. The project is not archived and the last push recorded is 2026-09-08. No releases were retrieved in the material supplied, so version numbers here come from the README text rather than from a release list. The CI and Docker build badges at the top of the README indicate both pipelines exist; they tell you nothing about whether the current build passes.
Editorial conclusion
Adopt it if your agent already writes code into a repository and you want diagrams to sit next to that code as .excalidraw files that re-export byte-identically. Skip it if you only need a diagram rendered once inside a chat window, or if you cannot run Node 20 or newer and a local browser canvas. Before wiring it into a repo, verify three things yourself: that the auto-started server on 127.0.0.1:3000 is reachable in your environment, that your MCP client works with the 2026-07-28 revision or falls back to the initialize handshake, and that the Obsidian or excalidraw.com round trip preserves the labels you care about.
Community notes