ExcaliDash MCP
ExcaliDash MCP lets an MCP client list, create, inspect, summarize, and atomically edit self-hosted ExcaliDash drawings.
List/search drawings with pagination (schema max 100 per page) and get drawing IDs.
Select or retrieve the default drawing for the MCP session/process; tools can also take an explicit
drawingId.Create an empty named drawing and optionally select it.
Summarize a drawing as text (bounds, element types, groups, element lines, arrow connections, layout warnings) and inspect one element with its bound children.
Apply 1–50 atomic semantic operations in one batch: add shapes, connect arrows/lines, set text/style, move/resize, align/distribute/layout, group/delete, and import raw Excalidraw elements; the schema also lists
revert_to_snapshot.Batches fail without saving if any operation is invalid, and concurrent-edit conflicts are retried up to three save attempts.
Support optional
clientBatchIdfor batch identity and return saved version/created-or-changed IDs.Run over stdio or Streamable HTTP against stable ExcaliDash REST APIs; the HTTP endpoint has no built-in auth and should be kept local or behind an authenticating proxy.
Caveat: README says history restore is unsupported, while the schema includes
revert_to_snapshot; verify that operation before relying on it.
Provides tools for viewing and editing Excalidraw drawings through a self-hosted ExcaliDash server, including listing and selecting drawings, creating new drawings, fetching structural summaries, inspecting elements, and applying batch semantic operations such as adding shapes, connectors, text, styling, alignment, and grouping.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ExcaliDash MCP List my drawings and summarize the 'Q3 roadmap' drawing."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ExcaliDash MCP
English | 한국어
An MCP server that lets AI agents read and edit drawings on a self-hosted ExcaliDash instance. It runs over stdio or Streamable HTTP and talks to the drawing REST API of stable ExcaliDash releases.
Agents send semantic operations such as "add a labeled rectangle" or "connect A to B". The server applies them to the drawing and saves the result only if the drawing has not changed since it was read.
This is an independent adapter, not part of the ExcaliDash project.
MCP client
│
├─ stdio ───────────────┐
│ │
└─ Streamable HTTP ─ ExcaliDash MCP ─ HTTPS ─ ExcaliDash
:9003/mcp /api/drawingsWhat it does
Lists drawings and searches them by name.
Creates empty drawings.
Summarizes a drawing as text: bounds, element types, groups, one line per element, arrows as
"A" → "B", and layout warnings.Returns the raw JSON of one element and its bound children.
Applies up to 50 operations as one batch. If any operation fails, nothing is saved.
Retries a batch on a fresh copy of the drawing when another editor saved first. It gives up after three save attempts.
Keeps the selected drawing per MCP session.
Open ExcaliDash editors receive each save, because ExcaliDash pushes saved scenes to them.
Related MCP server: excalidash-mcp
Requirements
ExcaliDash 0.6.0 or later. Tested with 0.6.5 and 0.6.7.
Node.js 22 or later, or Docker Compose.
An ExcaliDash account API key with the
Read drawingsandWrite drawingsscopes.
The server calls only the endpoints that stable ExcaliDash allows for API keys: GET /api/drawings, POST /api/drawings, and GET and PUT /api/drawings/:id. You do not need to turn on the ExcaliDash AI features.
To check that a key works, list one drawing:
curl -sS -H "Authorization: Bearer $EXCALIDASH_API_KEY" \
'https://your-excalidash/api/drawings?limit=1'A response like {"drawings":[...],"totalCount":...} means the key and URL are correct.
Create an API key
In ExcaliDash, open Settings > API Keys.
Enter a name.
Select
Read drawingsandWrite drawings.Create the key and copy it. ExcaliDash shows the full key only once.
The server does not use the collection scopes.
Run with Docker
Create the environment file:
cp .env.example .env chmod 600 .envSet the ExcaliDash URL and the API key in
.env:EXCALIDASH_URL=https://draw.example.com EXCALIDASH_API_KEY=exd_your_key MCP_PORT=9003If ExcaliDash runs on the same host, use
http://host.docker.internal:6767. Inside the container,localhostis the container itself.Build and start the container:
docker compose up -d --buildCheck that the server is healthy:
curl --fail http://127.0.0.1:9003/health
The MCP endpoint is http://127.0.0.1:9003/mcp. To follow the logs, run docker compose logs -f excalidash-mcp. To stop the server, run docker compose down.
Compose publishes the port on 127.0.0.1 only. The container runs as a non-root user with a read-only root filesystem and no Linux capabilities.
Connect an MCP client
GJC
Register the server in your user configuration:
gjc mcp add excalidash --type http --url http://127.0.0.1:9003/mcpAdd --project to write ./.gjc/mcp.json instead. Sessions load registered servers at startup. To keep this server out of sessions that do not need it, add "autoload": false to its entry:
{
"mcpServers": {
"excalidash": {
"type": "http",
"url": "http://127.0.0.1:9003/mcp",
"autoload": false
}
}
}Run gjc mcp list to see whether each server loads at startup.
Other clients
Any client that supports Streamable HTTP can use http://127.0.0.1:9003/mcp. Most clients accept this shape:
{
"mcpServers": {
"excalidash": {
"type": "http",
"url": "http://127.0.0.1:9003/mcp"
}
}
}Stdio
To run the server as a local process instead of a container, build it first:
npm ci
npm run buildThen point the client at dist/index.js:
{
"mcpServers": {
"excalidash": {
"command": "node",
"args": ["/absolute/path/to/excalidash-mcp/dist/index.js"],
"env": {
"EXCALIDASH_URL": "https://draw.example.com",
"EXCALIDASH_API_KEY": "${EXCALIDASH_API_KEY}"
}
}
}
}Example prompts
List my ExcaliDash drawings.
Select the "Service architecture" drawing and summarize it.
Create a drawing with an API Gateway, a Worker, and PostgreSQL, and connect them in request order.Tools
Tool | What it does |
| Lists drawings, 50 per page by default and up to 200. Accepts |
| Sets the drawing that later calls use by default. |
| Returns the selected drawing ID for this session. |
| Creates an empty drawing and selects it unless |
| Returns the text summary of a drawing. |
| Returns one element as JSON with its bound children. |
| Applies 1 to 50 operations as one batch and returns the saved version and the IDs it created or changed. |
get_drawing_summary, inspect_drawing_element, and apply_drawing_ops accept an optional drawingId. Without it, they use the selected drawing.
Summary format
Drawing "Architecture" (b54507c2-2879-407b-b8e0-f3fe8ec08c91) version 5, 6 elements
Bounds: (0, 0) to (580, 80), 580×80
Types: rectangle 1, text 3, ellipse 1, arrow 1
Elements:
- rectangle juM5PXi-FY8F8lgV0000 at (0, 0) 200×80 "API Gateway"
- ellipse I4bAeG9TIwvE5kPL0002 at (400, 0) 180×80 "PostgreSQL" [backgroundColor=#b2f2bb]
Connections:
- "API Gateway" juM5PXi-FY8F8lgV0000 → "PostgreSQL" I4bAeG9TIwvE5kPL0002 (arrow PuNysUewh-oifpN90004 "query")Labels inside a shape or on an arrow appear on that element's line. Element lines list only styles that differ from the Excalidraw defaults, plus frame and group membership. An arrow end that is not bound to a shape appears as (unbound).
A Warnings section lists shapes that partly overlap and labels larger than their container, up to 20 entries. A shape fully inside another shape is not reported, because panels and cards are drawn that way.
Operations
Each operation is a JSON object with an op field.
| Fields | Effect |
|
| Adds a |
|
| Draws an |
|
| Changes a text element, the label of a shape or arrow, or the name of a frame. |
|
| Changes the style of one element. |
|
| Moves an element by an offset or to a position. |
|
| Sets the width and height. |
|
| Aligns 2 to 100 elements to |
|
| Spaces 2 to 100 elements along the |
|
| Arranges elements in a row, a column, or a |
|
| Puts 2 to 100 elements in a new group. |
|
| Deletes an element and its label, and unbinds arrows attached to it. |
|
| Adds raw Excalidraw elements and fills in missing fields. |
Moving or resizing an element also moves its label, moves the contents of a frame, and redraws the arrows attached to it.
style accepts only these keys: strokeColor, backgroundColor, fillStyle (hachure, cross-hatch, solid, or zigzag), strokeWidth, strokeStyle (solid, dashed, or dotted), roughness (0 to 2), opacity (0 to 100), fontSize, fontFamily, textAlign (left, center, or right), and roundness (sharp or round). Any other key fails the batch.
An add_shape with a ref lets later operations in the same batch use that ref in place of an element ID:
{
"ops": [
{
"op": "add_shape",
"ref": "api",
"shape": "rectangle",
"x": 100,
"y": 100,
"w": 240,
"h": 100,
"label": "API Gateway"
},
{
"op": "add_shape",
"ref": "db",
"shape": "ellipse",
"x": 500,
"y": 100,
"w": 240,
"h": 100,
"label": "PostgreSQL"
},
{ "op": "connect", "fromId": "api", "toId": "db", "label": "query" }
]
}Environment variables
Name | Required | Default | Description |
| Yes | Base URL of ExcaliDash. The server adds | |
| Yes | Account API key with the | |
| No | Alias for | |
| No | Drawing to select when a session starts. | |
| No |
| HTTP bind address inside the container. |
| No |
| HTTP port inside the container. |
| No |
| Largest accepted HTTP request body, in bytes. |
| No |
| Most concurrent MCP sessions. Further sessions get HTTP 429. |
| No |
| Time in milliseconds before an idle session is closed. |
| No |
| Host port that Compose publishes on |
Security
The HTTP endpoint has no authentication of its own. Anyone who can reach it can read and edit every drawing the API key can. Keep it on 127.0.0.1, as the Compose file does, or behind a proxy that authenticates users. Do not publish it on a LAN address such as 0.0.0.0:9003:8080.
The server checks the Host and Origin headers on /mcp. That check stops DNS rebinding from a browser. It does not stop a client that connects directly, because that client can send any Host value.
The API key can read and change every drawing its owner has.
Keep
.envout of Git. The repository's.gitignorealready excludes it.Keep the key out of logs, issues, and screenshots.
If the key leaks, revoke it in ExcaliDash Settings > API Keys and create a new one.
Limitations
Each save replaces the whole scene. If a person edits the same drawing at the same time, their autosave can conflict with the agent's save. The server then re-applies the batch to the newer drawing. After three conflicts in a row, the tool returns an error.
The server estimates text size from the character count. The editor measures text again after it loads the fonts.
There are no tools for collections, for deleting whole drawings, or for restoring history. ExcaliDash does not accept API keys on its history endpoints.
The selected drawing is lost when the HTTP session ends. Pass
drawingIdto avoid depending on it.
Develop
npm ci
npm test
npm run start:httpnpm test builds the project and runs the unit and integration tests. They cover the operations, the summary, conflict retries, the stdio and HTTP transports, and session limits.
npm run test:e2e runs the server against real ExcaliDash containers. It needs Docker. It starts the ExcaliDash backend and frontend images on a private network, creates an admin user and an API key, runs the MCP tools, and checks the saved drawing. It removes the containers when it finishes. Set EXCALIDASH_TAG to test another ExcaliDash version:
EXCALIDASH_TAG=0.6.5 npm run test:e2eTroubleshooting
HTTP 401 Unauthorized
The API key is wrong or revoked. Create a new key in ExcaliDash.
HTTP 403 Forbidden
The API key lacks the Read drawings or Write drawings scope. Drawing-scoped agent tokens from ExcaliDash 0.6.0-dev builds do not work on stable releases. Create an account API key.
HTTP 404 or "Drawing not found"
The drawing ID is wrong, or the drawing belongs to another user. Run list_drawings to get the right ID.
"Drawing changed concurrently 3 times in a row"
Someone else saved the drawing before each of the three save attempts. Wait until the other editor stops, then run the request again.
"No drawing selected"
Call select_drawing after list_drawings, or pass drawingId to the tool.
The container cannot reach ExcaliDash
EXCALIDASH_URL probably points to localhost. Inside the container, use http://host.docker.internal:6767 for a service on the same host.
Port 9003 is already in use
Set another port in .env, for example MCP_PORT=9010. Then change the client URL to http://127.0.0.1:9010/mcp.
License
Available Tools
7 toolsapply_drawing_opsA
Atomically apply up to 50 semantic operations. Uses drawingId when provided, otherwise the selected drawing. Read the summary first.
Inputs: ops (required), drawingId, clientBatchId.
create_drawingB
Create a new empty Excalidraw drawing and optionally select it as the default target.
Inputs: name (required), select.
get_drawing_summaryA
Read a compact structural summary of a drawing. Uses drawingId when provided, otherwise the selected drawing.
Inputs: drawingId.
get_selected_drawingA
Return the drawing currently selected by this MCP process.
Inputs: no named parameters.
inspect_drawing_elementB
Inspect one element and its bound children. Uses drawingId when provided, otherwise the selected drawing.
Inputs: elementId (required), drawingId.
list_drawingsA
List ExcaliDash drawings available to the account API key. Use this before selecting a drawing.
Inputs: limit, offset, search.
select_drawingA
Select an Excalidraw drawing as the default target for subsequent tools in this MCP process.
Inputs: drawingId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct purpose: selection state vs. catalog listing vs. selection mutation vs. creation vs. summary reading vs. element inspection vs. operations application. There is no overlapping or ambiguous tool that could cause an agent to misselect. The descriptions clearly delineate responsibilities.
All tool names follow a consistent verb_noun pattern using snake_case, with verbs like get, list, select, create, inspect, and apply. The pattern is predictable and uniform across the set, making it easy for an agent to infer behavior from the name.
With exactly 7 tools, the set is well-scoped for a drawing management MCP. Each tool serves a clear, non-redundant function, and the count is neither too sparse nor overwhelming for the stated purpose.
The toolset covers listing, creating, selecting, reading summaries, inspecting elements, and applying operations, which are core workflows. A notable gap is the absence of a delete_drawing tool, and there is no explicit tool for updating drawing metadata, but these are minor and can be worked around.
Related MCP Connectors
OCR, transcription, file extraction, and image generation for AI agents via MCP.
A shared Excalidraw board that people and agents draw on together
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Design canvas for agents: create, edit, render and export Figma-shaped designs over MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables creation, management, and export of Excalidraw drawings through natural language. Supports CRUD operations on drawings and export to SVG, PNG, and JSON formats with file-based storage.8-
- FlicenseNot gradedqualityCmaintenanceMCP server that lets Claude (and other MCP clients) create, list, read, update, and delete drawings in ExcaliDash via its REST API. It allows users to create diagrams directly from natural language commands like 'draw a flowchart'.-
- AlicenseNot gradedqualityDmaintenanceMCP server for Excaliwow that lets AI agents create, read, render, manage, and edit diagrams through the Excaliwow REST API. It provides 18 tools for diagram generation, editing, reading, exporting, and organization, running over stdio for any MCP client.Apache 2.0
- AlicenseAqualityBmaintenanceEnables AI agents to create and manage ExcaliDash drawings through MCP by creating drawings, editing shapes and text, connecting elements, adding images, and organizing drawings into collections.177 npm1MIT