Skip to main content
Glama
ExcaliDash MCP

ExcaliDash MCP

by chlee1001

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/drawings

What 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 drawings and Write drawings scopes.

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

  1. In ExcaliDash, open Settings > API Keys.

  2. Enter a name.

  3. Select Read drawings and Write drawings.

  4. Create the key and copy it. ExcaliDash shows the full key only once.

The server does not use the collection scopes.

Run with Docker

  1. Create the environment file:

    cp .env.example .env
    chmod 600 .env
  2. Set the ExcaliDash URL and the API key in .env:

    EXCALIDASH_URL=https://draw.example.com
    EXCALIDASH_API_KEY=exd_your_key
    MCP_PORT=9003

    If ExcaliDash runs on the same host, use http://host.docker.internal:6767. Inside the container, localhost is the container itself.

  3. Build and start the container:

    docker compose up -d --build
  4. Check 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/mcp

Add --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 build

Then 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

list_drawings

Lists drawings, 50 per page by default and up to 200. Accepts search, limit, and offset.

select_drawing

Sets the drawing that later calls use by default.

get_selected_drawing

Returns the selected drawing ID for this session.

create_drawing

Creates an empty drawing and selects it unless select is false.

get_drawing_summary

Returns the text summary of a drawing.

inspect_drawing_element

Returns one element as JSON with its bound children.

apply_drawing_ops

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.

op

Fields

Effect

add_shape

shape, x, y, optional w, h, label, style, ref

Adds a rectangle, ellipse, diamond, text, or frame. A label on a rectangle, ellipse, or diamond becomes text bound inside it. On a frame, it becomes the frame name.

connect

fromId, toId, optional label, style, arrowType

Draws an arrow (default) or a line between two elements and binds both ends.

set_text

id, text

Changes a text element, the label of a shape or arrow, or the name of a frame.

set_style

id, style

Changes the style of one element.

move

id, either dx and dy or x and y

Moves an element by an offset or to a position.

resize

id, w, h

Sets the width and height.

align

ids, alignment

Aligns 2 to 100 elements to left, center, right, top, middle, or bottom of the first one.

distribute

ids, direction, optional gap

Spaces 2 to 100 elements along the horizontal or vertical axis, evenly or gap pixels apart.

layout

ids, direction, optional gap, columns, x, y

Arranges elements in a row, a column, or a grid.

group

ids

Puts 2 to 100 elements in a new group.

delete

id

Deletes an element and its label, and unbinds arrows attached to it.

import_elements

elements

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

EXCALIDASH_URL

Yes

Base URL of ExcaliDash. The server adds /api unless the URL already ends with it.

EXCALIDASH_API_KEY

Yes

Account API key with the Read drawings and Write drawings scopes.

EXCALIDASH_TOKEN

No

Alias for EXCALIDASH_API_KEY. Used only when EXCALIDASH_API_KEY is empty.

EXCALIDASH_DRAWING_ID

No

Drawing to select when a session starts.

MCP_HTTP_HOST

No

0.0.0.0

HTTP bind address inside the container.

MCP_HTTP_PORT

No

8080

HTTP port inside the container.

MCP_MAX_BODY_BYTES

No

10485760

Largest accepted HTTP request body, in bytes.

MCP_MAX_SESSIONS

No

64

Most concurrent MCP sessions. Further sessions get HTTP 429.

MCP_SESSION_IDLE_MS

No

1800000

Time in milliseconds before an idle session is closed.

MCP_PORT

No

9003

Host port that Compose publishes on 127.0.0.1.

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 .env out of Git. The repository's .gitignore already 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 drawingId to avoid depending on it.

Develop

npm ci
npm test
npm run start:http

npm 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:e2e

Troubleshooting

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

MIT

Available Tools

7 tools
apply_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

    A3.9/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP 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'.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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