Content
# excalidash-mcp
**Let your AI coding agent draw on your whiteboard.** Works with Claude Code, Cursor, Codex or any
other tool that speaks MCP. It turns a description of a diagram into real Excalidraw elements on your
self-hosted [ExcaliDash](https://github.com/ZimengXiong/ExcaliDash), and they appear live in every
browser that has the board open. No refresh needed.
<sub>Eight nodes and eight edges, written as plain text. No coordinates by hand.</sub>
[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
## Why
Ask a language model for a diagram and it has to invent pixel coordinates. It is bad at that, and the
result shows: arrows cut through boxes, labels hide underneath them, text overflows its container.
So don't ask it to. Describe the **structure**, meaning nodes and edges, and let a layout engine do
the geometry. Same graph, both ways:
| ❌ Model picks coordinates | ✅ Model picks structure |
|---|---|
|  |  |
| Arrows through boxes, labels clipped | `draw_graph` + dagre |
## Quick start
You need a running ExcaliDash instance and a user account for the agent to draw as.
```bash
git clone https://github.com/davifernan/excalidash-mcp.git
cd excalidash-mcp && npm install
```
Add it to your MCP client. This is `~/.mcp.json` for Claude Code; Cursor, Codex and the rest use the
same shape in their own config file:
```json
{
"mcpServers": {
"excalidash": {
"command": "node",
"args": ["/path/to/excalidash-mcp/src/index.js"],
"env": {
"EXCALIDASH_BACKEND_URL": "https://draw.example.com/api",
"EXCALIDASH_URL": "https://draw.example.com",
"EXCALIDASH_EMAIL": "agent@example.com",
"EXCALIDASH_PASSWORD": "your-agent-password"
}
}
}
}
```
> [!TIP]
> Point `EXCALIDASH_BACKEND_URL` at your instance's **`/api`** path. The ExcaliDash frontend proxies
> it to the backend already, so no custom Nginx config and no exposed ports are needed.
> See [docs/setup.md](docs/setup.md) for the details and the same-host alternative.
## Drawing
Ask for a diagram in plain language and the agent writes the DSL. This is what it writes:
```
direction LR
title 'Deploy Pipeline'
node push 'git push' color=gray fill=gray
node lint 'Lint' color=blue fill=blue
node test 'Test Suite' color=blue fill=blue
node gate 'All green?' shape=diamond color=orange fill=orange
node build 'Build Image' color=purple fill=purple
node stage 'Staging' color=green fill=green
node prod 'Production' color=green fill=green
node roll 'Rollback' color=red fill=red
edge push -> lint
edge push -> test
edge lint -> gate
edge test -> gate
edge gate -> build 'yes'
edge gate -> roll 'no'
edge build -> stage 'auto'
edge stage -> prod 'manual approve'
edge prod -> roll 'on error' color=red style=dashed
```
Boxes are sized to fit their labels, long labels wrap, edge labels get their own space, and parallel
edges fan apart instead of stacking. **Directions:** `LR`, `TB`, `RL`, `BT` · **Shapes:** `rect`,
`circle`, `diamond` · **Colors:** `blue`, `green`, `orange`, `purple`, `red`, `yellow`, `teal`,
`pink`, `gray`, or any hex code.
For annotations, legends and free-form sketches there is a second DSL that takes absolute
coordinates. See [docs/scene-dsl.md](docs/scene-dsl.md).
## Sharing
The agent signs in as its own account, so the boards it draws on belong to that account and nobody
else can open them. Ask it to share one when it's done:
```
share_board(board_id, with="you@example.com", access="edit")
```
The board then appears under **Shared with me** on your dashboard. `access="none"` takes it away
again. Pass an email address: the instance matches on fragments, so anything that isn't an exact
address or name is handed back for you to confirm rather than guessed at.
If every board should reach you anyway, set a standing recipient:
```json
"EXCALIDASH_SHARE_WITH": "you@example.com"
```
Every board the agent creates is then shared with you the moment it exists, so you can watch it being
drawn. This one shares **view** access, because the board is still being worked on: drawing rewrites
the board's contents, and `draw_graph` replaces them outright, so anything you added would be gone on
the next call. Append `:edit` if you want it anyway. A user id works in place of the address and
skips the lookup entirely.
## Tools
| Tool | What it does |
|------|--------------|
| `draw_graph` | Node/edge diagram with automatic layout. **Start here.** |
| `draw_scene` | Place elements at absolute coordinates |
| `read_me` | Format cheat sheet; the agent calls this once before drawing |
| `list_boards` · `create_board` · `read_board` | Board management |
| `share_board` | Give a person access to a finished board, or take it away |
| `update_element` · `delete_elements` · `rename_element` | Edit by name, live |
| `board_history` · `restore_version` | Browse and restore snapshots<sup>†</sup> |
| `export_png` | Render a board to PNG, framed on the drawing |
<sup>†</sup> Version history needs the snapshot API from
[PR #138](https://github.com/ZimengXiong/ExcaliDash/pull/138), merged into ExcaliDash in April 2026.
Any current version has it.
## How it works
The server pushes over Socket.IO **and** persists over REST, which is why elements show up in an open
board immediately and still survive a reload. Every diagram in this README was drawn by the server
itself and exported with `export_png`.
## Docs
- [Diagramming skill](skills/diagramming/SKILL.md): what to do and what to avoid, for agents that draw
- [Examples](docs/examples.md): more diagrams, each with the DSL that produced it
- [Setup](docs/setup.md): ExcaliDash instance, the `/api` path, environment variables
- [Scene DSL](docs/scene-dsl.md): manual placement, element reference
- [Troubleshooting](docs/troubleshooting.md): HTML instead of JSON, redirects, missing live updates,
a board link that won't open, sign-ins that start failing on their own
## License
MIT
