What can you do with this server?

The Excalidraw MCP Server provides a structured API for creating, modifying, and managing Excalidraw diagrams, enabling seamless integration with LLMs and other platforms. Capabilities include: * Create/Update/Delete Elements: Generate or modify shapes like rectangles, ellipses, and text * Query Elements: Filter and retrieve elements based on criteria * Manage Resources: Access scene information, libraries, and themes * Organize Elements: Group, ungroup, align, distribute, lock, and unlock elements * Flexible Integration: Works with Claude Desktop, Cursor, and Docker for deployment

Which integrations are available for this server?

Supports containerized deployment of the MCP server for simplified integration and consistent environment. Enables creation, modification, and manipulation of Excalidraw diagrams, including element control, grouping, alignment, and resource management. Provides installation and dependency management through npm, allowing users to easily set up and run the MCP server.

How do I use Excalidraw MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Excalidraw MCP Server create a flowchart showing user login process" 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.

de en es ja ko ru zh

Excalidraw MCP Server

by yctimlin

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Excalidraw MCP Server, CLI & Agent Skill

Docker Build & Push NPM Version License

mcp-excalidraw-server gives AI agents a live Excalidraw canvas they can draw on, look at, refine, and save into your repo. Your agent creates architecture diagrams and flowcharts programmatically, sees its own work via screenshots, fixes layout problems, and exports .excalidraw files you can commit next to your code.

One canvas, three ways to drive it:

Agent Skill + CLI — recommended for coding agents (Claude Code, Codex CLI, Cursor, OpenCode): npx -y mcp-excalidraw-server <command>. Zero config, auto-starts the canvas, composable JSON in/out.
MCP Server — 26 tools over stdio for any Model Context Protocol client (Claude Desktop, Cursor, Codex CLI, Antigravity, ...). Speaks MCP 2026-07-28 (server/discover, per-request _meta envelope, tool calls without a handshake) and stays compatible with 2025-era clients that open with initialize.
REST API — plain HTTP for LangChain and custom frameworks.

Core drawing runs fully local (Node ≥ 20, MIT licensed) — no API keys. Mermaid conversion runs in the local browser canvas; share is optional and uploads an encrypted scene to excalidraw.com.

Demo

AI agent drawing an architecture diagram on a live Excalidraw canvas via MCP

AI agent creates a complete architecture diagram from a single prompt (4x speed). Watch full video on YouTube

Related MCP server: Mermaid MCP Server

What It Is

Ask your agent to "draw the architecture of this service" and it produces a real, editable Excalidraw diagram — not a one-shot image. Because the agent can query, screenshot, and update individual elements, it iterates until labels fit, nothing overlaps, and arrows route cleanly; then it exports the result as a .excalidraw file that lives in your repo and gets updated when the code changes.

Under the hood there are two processes, one product:

Canvas server: Excalidraw web UI + REST API + WebSocket real-time sync (default http://127.0.0.1:3000)
A thin front-end of your choice: the CLI, the MCP stdio server, or raw HTTP — all drive the same canvas

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. status only inspects the current server state. Set EXCALIDRAW_NO_AUTOSTART=1 to opt out.

How We Differ from the Official Excalidraw MCP

Excalidraw has an official MCP — a chat widget that streams a diagram inline from a single prompt (the model gets two tools: a format reference and create_view). It's great for "draw me a cat" in Claude or ChatGPT. We solve a different problem: giving coding agents a persistent canvas workbench.

	Official Excalidraw MCP	This Project
Approach	Prompt in, diagram out (one-shot widget)	Programmatic element-level control (CLI + 26 MCP tools)
State	Checkpoints inside the chat widget	Persistent live canvas with real-time sync
Element CRUD	Declarative re-send with delete markers	Full create / read / update / delete per element
AI sees the canvas	No	`describe` (structured text) + `screenshot` (image)
Iterative refinement	Regenerate from checkpoint	Draw → look → adjust → look again, element by element
Layout tools	No	align, distribute, group / ungroup, lock, duplicate
File I/O	No model-facing export	`.excalidraw` export/import — diagrams as repo artifacts
Snapshot & rollback	Widget-side checkpoints	Named server-side snapshots
Mermaid conversion	No	`mermaid` / `create_from_mermaid`
Shareable URLs	Widget-only	`share` / `export_to_excalidraw_url`
Viewport control	Camera animations	`set_viewport` (zoom-to-fit all or selected elements, center on one element, manual zoom)
Works without MCP	No	Yes — CLI + agent skill + REST API
Multi-agent	Single chat	Multiple agents on the same canvas concurrently

TL;DR — The official MCP shows Excalidraw diagrams in your chat. This project gives your coding agent a full Excalidraw workbench: a canvas it can draw on, inspect, refine, and commit to your repo.

What's New

Current package version: 2.0.0. The current release line is v2.0 — Interchange-Grade Exports & MCP 2026-07-28.

v2.0 — Interchange-Grade Exports & MCP 2026-07-28

Breaking: Node >= 20 required (was 18) — the MCP TypeScript SDK v2 sets the floor. Everything else is backward compatible, including existing MCP client configs.
MCP protocol revision 2026-07-28: modern clients can call tools statelessly without an initialization handshake (server/discover, per-request _meta envelopes); legacy initialization-based clients keep working unchanged. (#98, thanks @anxkhn)
Exports render everywhere now: .excalidraw / .excalidraw.md files contain real Excalidraw elements — shape and arrow labels as bound text, 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). (#93, #95)
Byte-stable exports: deterministic ids, seeds, and key order — re-exporting an unchanged scene is byte-identical, so committed diagrams and vault files never produce phantom git diffs, and Obsidian block references survive re-exports.
Obsidian vault fixes: Windows/CRLF .excalidraw.md files import correctly (#94, thanks @cason-miles); ## Text Elements block references now cover shape labels too.
Element fields are never silently dropped: unknown Excalidraw properties (containerId, textAlign, originalText, ...) pass through the server intact — fixes browser-edited text vanishing after sync. (#92, thanks @junuxyz)
Mermaid conversion merges into the existing canvas instead of replacing it, and each browser tab holds exactly one WebSocket connection (no more doubled labels). (#91)
Viewport control: set_viewport gains scrollToElementIds (multi-element zoom-to-fit) and viewportZoomFactor, with strict single-mode validation and real error reporting. (#86, thanks @acercyc)
Dark mode: the canvas page chrome follows the editor theme and persists it across reloads. (#89, thanks @danielsvane)

v1.1 — CLI-First

First-class CLI: every capability is now a composable command — npx -y mcp-excalidraw-server add|query|describe|screenshot|export|import|mermaid|snapshot|arrange|share|... — JSON on stdout, meaningful exit codes. Also installed as the excalidraw-canvas alias.
Zero-setup: canvas-driving CLI commands and the MCP server auto-start the canvas server if it isn't running (closes #66). Opt out with EXCALIDRAW_NO_AUTOSTART=1.
apply: multi-op patches ({"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}) in a single invocation.
install-skill: npx -y mcp-excalidraw-server install-skill --dir <skills-root> copies the portable agent skill into the directory your agent chooses (project or global), cleanly replacing older versions.
Skill is now CLI-first and no longer needs a cloned repo or configured MCP server to work.
Typed queries: query --filter locked=true --filter label.text=API — booleans, numbers, and nested keys work.
Internals: shared core library (src/core/) behind both the CLI and MCP server; canvas groupIds are the source of truth for grouping (ungroup now works across restarts); node-fetch dropped; MCP version metadata derived from package.json; canvas server writes a pidfile and shuts down cleanly.

Installation

The only prerequisite is Node.js ≥ 20.

Easiest: let your agent install it

Copy this into your coding agent — it installs the portable skill into the project/global skill directory that agent already knows how to use, then verifies it by drawing a test diagram:

Install the Excalidraw canvas toolkit so you can draw diagrams for me:

1. Choose the right skill directory for this agent and scope (project or global).
2. Run: npx -y mcp-excalidraw-server install-skill --dir <that-skills-directory>
3. Read the installed excalidraw-skill/SKILL.md so you know the drawing workflow.
4. Start the canvas with: npx -y mcp-excalidraw-server start
   then tell me to open http://127.0.0.1:3000 in my browser (screenshots need an open tab).
5. Draw a small test diagram — two labeled boxes connected by an arrow — take a
   screenshot, and show me the result to confirm everything works.

Manual install

You are...	Install with	Then
Modern coding agent	`npx -y mcp-excalidraw-server install-skill --dir <skills-root>`	Let the agent choose project/global scope and its skill root
Claude Code shortcut	`npx -y mcp-excalidraw-server install-skill`	Installs to `~/.claude/skills` for backward compatibility
Codex shortcut	`npx -y mcp-excalidraw-server install-skill --target codex`	Installs to `~/.codex/skills` for backward compatibility
MCP client user (Claude Desktop, Cursor, ...)	Add the npx config below	See Configure MCP Clients
CLI user / scripting	Nothing — `npx -y mcp-excalidraw-server <command>`	See CLI Reference
Contributor / from source	`git clone` + `npm ci` + `npm run build`	See Quick Start (From Source / Docker)

There is no separate server setup: any drawing command auto-starts the local canvas server on http://127.0.0.1:3000.

60-Second Quick Start (CLI)

No clone, no config:

# start the canvas (drawing commands auto-start it too) and open it
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000   # browser tab enables screenshots & mermaid

# draw something
echo '[
  {"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server","backgroundColor":"#a5d8ff"},
  {"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database","backgroundColor":"#99e9f2"},
  {"type":"arrow","x":0,"y":0,"startElementId":"api","endElementId":"db","text":"SQL"}
]' | npx -y mcp-excalidraw-server add

# let your agent see its work
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png

# diagrams as repo artifacts
mkdir -p docs
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw

# or straight into an Obsidian vault (.md extension → Obsidian Excalidraw plugin format)
npx -y mcp-excalidraw-server export --out ~/vault/diagrams/architecture.excalidraw.md

Give your agent the full playbook:

npx -y mcp-excalidraw-server install-skill --dir <skills-root>
npx -y mcp-excalidraw-server install-skill --print-source  # inspect bundled source path

Security note: The canvas server binds 127.0.0.1 only by default. If you expose it on a network interface (HOST=0.0.0.0), put network-level access controls in front — the API has no built-in authentication.

Agent Skill

The skill at skills/excalidraw-skill/ teaches agents the full workflow — layout planning, the screenshot-verify-fix quality loop, arrow routing, anti-patterns, snapshots, and file I/O. It works through the CLI (preferred, zero setup), MCP tools (if configured), or raw REST — in that order.

npx -y mcp-excalidraw-server install-skill --dir <skills-root>

The command copies the bundled excalidraw-skill/ directory into <skills-root>/excalidraw-skill. Let your agent choose whether that root should be project-level or global. Re-running install-skill upgrades in place — it replaces the target directory, so files removed upstream don't linger.

Where the skill shines:

Diagrams as code artifacts: export .excalidraw files into the repo, commit them, re-import + refine when the architecture changes.
Obsidian vaults: export with a .excalidraw.md extension and the file opens natively in the Obsidian Excalidraw plugin — no compatibility-mode warning, block references and sync work; import reads both plain and lz-string-compressed vault files back.
Self-verifying diagrams: the agent screenshots its own work and fixes truncation/overlap before calling it done.
No-MCP environments: CI jobs, plain shells, and frameworks get the same capabilities through the CLI.

CLI Reference

npx -y mcp-excalidraw-server <command> or (after npm i -g mcp-excalidraw-server) excalidraw-canvas <command>.

Conventions: JSON results on stdout — except describe (plain text by design) and raw-content output when --out is omitted (export prints the scene JSON, screenshot --format svg prints SVG). Diagnostics on stderr. Exit codes: 0 ok, 1 error, 2 usage, 3 canvas unreachable, 4 browser tab required. Canvas URL from EXPRESS_SERVER_URL or --url. Canvas-driving commands auto-start the server; status only reports current state. Explicit start overrides the EXCALIDRAW_NO_AUTOSTART=1 opt-out (it's user intent, not auto-start).

Command	Description
`start` / `stop` / `status`	Manage the canvas server (detached; `stop` identity-checks the live server via `/health` before signaling)
`add [file\|-]`	Batch-create elements from a JSON array (file or stdin); `--one '{...}'` for a single element
`apply [file\|-]`	One-call multi-op patch: `{"create":[...],"update":[{"id":"a","set":{...}}],"delete":["id"]}`
`get <id>` / `delete <id...>`	Read / remove elements
`update <id> --set '{...}'`	Update an element
`query`	`--type`, `--bbox x0,y0,x1,y1`, `--filter k=v` (typed, nested keys), `--filter-json '{...}'`
`describe`	AI-readable scene summary (plain text)
`screenshot`	`--out f.png`, `--format png\|svg`, `--no-background` (browser tab required)
`export [--out f.excalidraw] [--format json\|obsidian]` / `import [file\|-] [--replace]`	Scene file I/O — a `.md` out path writes Obsidian's `.excalidraw.md` format; `import` reads it back
`mermaid [file\|-]`	Mermaid → canvas (browser tab required)
`snapshot save\|list\|restore <name>`	Named snapshots
`arrange align\|distribute\|group\|ungroup\|lock\|unlock\|duplicate`	Layout ops (`--ids a,b,c`, `--to left\|horizontal\|...`)
`share`	Encrypted upload → shareable excalidraw.com URL
`clear --yes`	Wipe the canvas
`install-skill [--dir <skills-root>]`	Install the portable agent skill

Labels and arrow bindings use the agent-friendly format everywhere in the CLI: "text" on any shape, "startElementId"/"endElementId" on arrows — normalization is automatic.

Configure MCP Clients

The MCP server runs over stdio. Since v1.1 the simplest config is npx — no clone, no absolute paths, and the canvas auto-starts:

Environment Variables

Variable	Description	Default
`EXPRESS_SERVER_URL`	URL of the canvas server	`http://127.0.0.1:3000`
`ENABLE_CANVAS_SYNC`	Enable real-time canvas sync	`true`
`EXCALIDRAW_NO_AUTOSTART`	Set `1` to disable canvas auto-start	(unset)
`EXCALIDRAW_EXPORT_DIR`	Base directory MCP file exports may write to	current working dir
`PORT` / `HOST`	Canvas server bind address	`3000` / `127.0.0.1`

Claude Desktop

Config location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

npx (recommended)

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Local (node)

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

Claude Code

npx (recommended)

claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server

Tip: for coding agents, the skill + CLI often beats MCP config entirely — let the agent pick its skill root, then run npx -y mcp-excalidraw-server install-skill --dir <skills-root>.

Local (node) - User-level (available across all projects):

claude mcp add excalidraw --scope user \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js

Docker

claude mcp add excalidraw --scope user \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

Manage servers:

claude mcp list              # List configured servers
claude mcp remove excalidraw # Remove a server

Cursor

Config location: .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global config)

npx (recommended)

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

Codex CLI

npx (recommended)

codex mcp add excalidraw -- npx -y mcp-excalidraw-server

Docker

codex mcp add excalidraw \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

Manage servers:

codex mcp list              # List configured servers
codex mcp remove excalidraw # Remove a server

OpenCode

Config location: ~/.config/opencode/opencode.json or project-level opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["npx", "-y", "mcp-excalidraw-server"],
      "enabled": true
    }
  }
}

Antigravity (Google)

Config location: ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Notes

Docker networking: Use host.docker.internal to reach the canvas server running on your host machine. On Linux, you may need --add-host=host.docker.internal:host-gateway or use 172.17.0.1. The Docker MCP image sets EXCALIDRAW_NO_AUTOSTART=1 (it has no frontend build) — run the canvas as its own container.
In-memory storage: The canvas server stores elements in memory. Restarting the server clears all elements — use export / snapshot for persistence.

MCP Tools (26 Total)

Category	Tools
Element CRUD	`create_element`, `get_element`, `update_element`, `delete_element`, `query_elements`, `batch_create_elements`, `duplicate_elements`
Layout	`align_elements`, `distribute_elements`, `group_elements`, `ungroup_elements`, `lock_elements`, `unlock_elements`
Scene Awareness	`describe_scene`, `get_canvas_screenshot`
File I/O	`export_scene`, `import_scene`, `export_to_image`, `export_to_excalidraw_url`, `create_from_mermaid`
State Management	`clear_canvas`, `snapshot_scene`, `restore_snapshot`
Viewport	`set_viewport`
Design Guide	`read_diagram_guide`
Resources	`get_resource`

Full schemas are discoverable via tools/list or in skills/excalidraw-skill/references/cheatsheet.md.

Viewport group focus can tune framing with viewportZoomFactor:

{
  "scrollToElementIds": ["id1", "id2", "id3"],
  "viewportZoomFactor": 0.85
}

scrollToElementIds zooms to fit every requested element, while scrollToElementId centers one element without changing the current zoom. Specify only one viewport mode per request. viewportZoomFactor accepts values greater than 0 and at most 1.

Quick Start (From Source / Docker)

From source (Node >= 20):

npm ci
npm run build
PORT=3000 npm run canvas          # canvas server (terminal 1)
node dist/index.js                # MCP server over stdio (terminal 2, usually launched by your MCP client)
node dist/bin.js status           # or drive the CLI straight from the build

Docker canvas server:

docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest

MCP server image: ghcr.io/yctimlin/mcp_excalidraw:latest (stdio; point EXPRESS_SERVER_URL at the canvas container).

Testing

CLI Smoke Test

npx -y mcp-excalidraw-server start
npx -y mcp-excalidraw-server status
npx -y mcp-excalidraw-server add --one '{"type":"rectangle","x":100,"y":100,"width":300,"height":200}'
npx -y mcp-excalidraw-server describe

Canvas Smoke Test (HTTP)

curl http://127.0.0.1:3000/health

Local Bind Regression Test

npm run test:bind

Canvas Browser Regression Tests

These Chromium tests build the app and start an isolated localhost server. They cover frame reload/reconnect, mixed scenes, failed-load sync protection, stale responses, clearing/deletion, Mermaid imports, and SVG export. They refuse to reuse an existing server; set CANVAS_TEST_PORT if port 51910 is occupied.

npx playwright install chromium
npm run type-check:frontend
npm run test:canvas

MCP Stdio Wire Test

Drives dist/index.js with raw JSON-RPC frames and checks both protocol eras: server/discover, tool calls sent without any handshake, refusal of unsupported protocol revisions and malformed _meta envelopes, and the legacy initialize path.

npm run test:mcp

MCP Smoke Test (MCP Inspector)

List tools:

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/list

Create a rectangle:

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/call --tool-name create_element \
  --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 \
  --tool-arg width=300 --tool-arg height=200

Frontend Screenshots (agent-browser)

If you use agent-browser for UI checks:

agent-browser install
agent-browser open http://127.0.0.1:3000
agent-browser wait --load networkidle
agent-browser screenshot /tmp/canvas.png

FAQ

How is this different from the official Excalidraw MCP?

The official Excalidraw MCP is a chat widget: you prompt, it streams a diagram into the conversation (the model gets two tools). This project is a workbench for coding agents: a persistent local canvas with element-level create/read/update/delete, layout tools, screenshots the model can see, snapshots, and .excalidraw file I/O — driveable via CLI, MCP, or REST. See the full comparison table.

Which AI tools does it work with?

Claude Code, Claude Desktop, Cursor, Codex CLI, OpenCode, and Google Antigravity are documented below — but any agent that can run shell commands can use the CLI, any MCP client can use the MCP server, and anything else (LangChain, custom apps) can use the REST API.

Can the AI actually see the diagram it drew?

Yes — that's the core feature. describe returns a structured text summary (ids, positions, labels, connections) and screenshot returns a rendered PNG. Agents use both to catch truncated labels, overlaps, and bad arrow routing, then fix them element by element.

Do I need a browser open?

Only for rendering-dependent features: screenshots, PNG/SVG export, viewport control, and Mermaid conversion (they render in the Excalidraw frontend). Creating, querying, updating elements and exporting .excalidraw JSON all work headless. The CLI exits with code 4 and tells you when a browser tab is needed.

Are my diagrams persistent?

The canvas is in-memory by design (restart = blank canvas). Persist by exporting .excalidraw files into your repo (export --out docs/architecture.excalidraw) or with named snapshots while working. Re-import a file to keep refining it later.

share encrypts the scene locally with AES-GCM before uploading; the decryption key is only in the URL fragment, which excalidraw.com's server never sees. Anyone you give the full link to can view the diagram.

Does it need an API key or cloud service?

No API key is required. Core drawing runs locally under MIT license. The only outbound call is the optional share upload to excalidraw.com.

Can I use it without configuring MCP?

Yes — that's the recommended path for coding agents: npx -y mcp-excalidraw-server install-skill --dir <skills-root> and the agent drives everything through the CLI. MCP configuration is only needed for chat clients like Claude Desktop.

Troubleshooting

CLI exit code 3 (canvas unreachable): the server is not running for an inspecting command such as status, auto-start is disabled (EXCALIDRAW_NO_AUTOSTART=1), or EXPRESS_SERVER_URL points at a non-loopback host. Run start explicitly or fix the env.
CLI exit code 4 (browser required): screenshots, image export, viewport, and mermaid conversion render in the frontend — open http://127.0.0.1:3000 in a browser and retry.
Canvas not updating: confirm EXPRESS_SERVER_URL points at the running canvas server (status shows the URL in use).
Updates/deletes fail after batch creation: ensure you are on a build that includes the batch id preservation fix (merged via PR #34).

Known Issues / TODO

Persistent storage: Elements are stored in-memory — restarting the server clears everything. Use export / snapshots as a workaround.
Image export requires a browser: screenshots and image export rely on the frontend doing the actual rendering. A headless rendering mode is planned.

Contributions welcome!

Development

npm run type-check
npm run build
npm run cli -- status      # run the CLI from the local build
npm run sync:skills        # after editing skills/excalidraw-skill, sync the repo-local agent copy

Bug reports and pull requests are welcome on GitHub issues. If this project helps you, a ⭐ helps others find it.

License

MIT © yctimlin — not affiliated with the Excalidraw team. Excalidraw is its own MIT-licensed project; this toolkit builds on it with love.

Links: npm package · GitHub · Issues · Demo video

Available Tools

11 tools

align_elementsC

Align elements to a specific position

ParametersJSON Schema

Name	Required	Description	Default
`alignment`	Yes
`elementIds`	Yes

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description is the only source of behavioral transparency. It fails to disclose whether alignment is relative to other elements or an absolute canvas position, what values like 'center' vs 'middle' mean, or any side effects. This ambiguity leaves the agent guessing about the tool's actual behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no redundancy or fluff. It is front-loaded with the action and resource. However, it errs on the side of underspecification, which slightly detracts from its effectiveness, though it remains concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations, no output schema, and two parameters, the description is not complete enough. It lacks information on return values, alignment semantics, and how it interacts with the canvas or selection. The sibling tools like distribute_elements and group_elements suggest a broader context that this description fails to address.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does not explain the meaning of the 'alignment' enum values (e.g., 'left', 'center', 'right', 'top', 'middle', 'bottom') or clarify what 'elementIds' refers to. The parameter names are self-evident but their precise semantics remain under-specified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action (Align) and target (elements) with an outcome ('to a specific position'). It distinguishes itself from generic tools but does not explicitly differentiate from closely related siblings like distribute_elements, so it misses the top score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, scenarios, or exclusions. The description is purely a bare definition without contextual usage advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_elementC

Create a new Excalidraw element

ParametersJSON Schema

Name	Required	Description	Default
`backgroundColor`	No
`fontFamily`	No
`fontSize`	No
`height`	No
`opacity`	No
`roughness`	No
`strokeColor`	No
`strokeWidth`	No
`text`	No
`type`	Yes
`width`	No
`x`	Yes
`y`	Yes

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. 'Create' implies a write operation, but it doesn't specify permissions needed, whether the element is saved immediately, if there are rate limits, or what happens on failure. This is inadequate for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that gets straight to the point without any wasted words. It's appropriately sized for the tool's basic purpose, though this conciseness comes at the cost of completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a creation tool with 13 parameters, 0% schema coverage, no annotations, and no output schema, the description is severely inadequate. It doesn't explain what an 'Excalidraw element' is, how parameters interact, what values are returned, or error conditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides no information about any of the 13 parameters, despite 0% schema description coverage. Parameters like 'type' with an enum or 'roughness' are completely unexplained, leaving the agent to guess their meaning and usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Create') and resource ('a new Excalidraw element'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'update_element' which might also create elements through updates, leaving room for ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'update_element' or 'query_elements'. There's no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_elementC

Delete an Excalidraw element

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention whether deletion is permanent, whether it cascades to dependent elements, any authorization requirements, or potential side effects. The terse statement leaves critical behavioral aspects undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one short sentence with no wasted words, making it highly concise and front-loaded. However, it is minimal to the point of missing valuable contextual information, so it earns a 4 rather than a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is the only source of completeness. It fails to explain return values, behavior on non-existent elements, or any other operational details. For a deletion tool, this is a significant gap in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the 'id' parameter's format, meaning, or how to obtain it. The description adds no value beyond the raw schema field definition, leaving the agent without context for correctly populating the required parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Delete an Excalidraw element' uses a specific verb (delete) and resource (Excalidraw element), clearly distinguishing it from sibling tools like create_element, update_element, and query_elements. It is unambiguous and action-oriented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It simply states the action without contextual cues, leaving the agent to infer usage purely from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

distribute_elementsD

Distribute elements evenly

ParametersJSON Schema

Name	Required	Description	Default
`direction`	Yes
`elementIds`	Yes

TDQS

D1.8/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It fails to state whether this tool modifies element positions, requires a selection, or affects layout. No side effects, limitations, or operational details are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely brief, but it is under-specified rather than impactful. It front-loads the core action, but fails to provide context that would be expected for a tool with two parameters and a direction enum.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has two parameters and appears to be a layout operation, the description is severely incomplete. There is no output schema, no annotations, and the description does not clarify what 'evenly' means spatially or how direction affects the operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention either parameter ('elementIds' or 'direction'). It adds no meaning beyond what the schema already shows, leaving the agent to infer the purpose of each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Distribute elements evenly' names a specific verb ('distribute') and resource ('elements'), but it is vague about what 'evenly' means (e.g., spacing, position, alignment). It does not distinguish from siblings like align_elements or group_elements, which could also involve arranging elements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, selection requirements, or which distribution scenarios it handles. Sibling tools like align_elements suggest related functionality, but the description does not clarify boundaries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_resourceD

Get an Excalidraw resource

ParametersJSON Schema

Name	Required	Description	Default
`resource`	Yes

TDQS

D1.3/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are absent, so the description carries the full burden of disclosing behavior. It only says 'Get' with no mention of read-only semantics, side effects, return format, or other behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only a single sentence, but this brevity reflects under-specification rather than conciseness. It contains zero useful information beyond what the tool name already conveys.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations and no output schema, the description is critically incomplete. It omits resource types, return values, example usage, and any distinguishing context, leaving the agent to guess the tool's function.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not explain the 'resource' parameter. While the schema provides an enum, the description adds no meaning about what each resource type represents or how to use them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get an Excalidraw resource' essentially restates the tool name without adding specificity. It does not enumerate the supported resource types (scene, library, theme, elements) nor differentiate from similarly named siblings like get_element or get_selection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. Sibling tools like get_element, get_selection, and export_scene clearly overlap, yet the description offers no context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

group_elementsC

Group multiple elements together

ParametersJSON Schema

Name	Required	Description	Default
`elementIds`	Yes

TDQS

C2.4/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, and the description only states the action without disclosing behavioral consequences such as whether a group object is created, whether elements are repositioned, or whether the operation is reversible. The description adds no behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise, front-loaded sentence with no extraneous words. It is efficient, though it sacrifices substance for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations, no output schema, and a single undocumented parameter, the description is insufficiently complete. It does not explain the effect on the canvas, expected return value, or any constraints, which is particularly problematic for a mutation-like tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention elementIds or explain what the array should contain, any constraints, or the relationship of these IDs. The description provides zero added meaning beyond the parameter name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Group') and resource ('elements'), clearly distinguishing it from siblings like ungroup_elements. It is minimal but not a bare tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as ungroup_elements, align_elements, or distribute_elements. There are no prerequisites or exclusions mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lock_elementsB

Lock elements to prevent modification

ParametersJSON Schema

Name	Required	Description	Default
`elementIds`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden. It states the intended effect (prevent modification) but does not disclose side effects, reversibility, permissions, or persistence. This is significantly under-specified for a mutating operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, direct, and front-loaded. Every word earns its place with no waste or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool that modifies state, the description lacks context on prerequisites, reversibility, and effects. Sibling tools like unlock_elements exist, but the description doesn't reference them, leaving the agent uncertain about the tool's broader usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter, elementIds, with 0% description coverage. The description says 'elements' but does not explain that the parameter is an array of element IDs or how to obtain them. The parameter name is self-explanatory, providing minimal additional value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Lock elements to prevent modification' with a specific verb (lock), resource (elements), and purpose (prevent modification). This distinguishes it from siblings like unlock_elements and other element operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when modification should be prevented, but provides no explicit when-to-use or alternatives (e.g., no mention of unlock_elements for reversal). It is clear enough for basic use but lacks decision guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_elementsC

Query Excalidraw elements with optional filters

ParametersJSON Schema

Name	Required	Description	Default
`filter`	No
`type`	No

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions 'optional filters' but doesn't disclose behavioral traits like whether this is a read-only operation, if it requires specific permissions, how results are returned (e.g., pagination), or any rate limits. This leaves significant gaps for a query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, clearly stating the tool's core function without unnecessary details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, 0% schema coverage, no output schema, and 2 parameters (one with an enum but unexplained), the description is incomplete. It doesn't cover key aspects like return values, error handling, or how to interpret the 'filter' object, making it inadequate for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It hints at 'optional filters' but doesn't explain what 'filter' or 'type' parameters mean, their formats, or how they interact. With 2 parameters and no schema descriptions, this adds minimal value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Query Excalidraw elements with optional filters' states the verb (query) and resource (Excalidraw elements), which is clear. However, it doesn't distinguish this tool from siblings like 'get_resource' or 'update_element'—it's vague about what makes 'query' different from 'get' or how it relates to other element operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. With siblings like 'get_resource' (which might retrieve elements) and 'create_element'/'update_element' for modifications, the description offers no context for choosing 'query_elements' over them or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ungroup_elementsB

Ungroup a group of elements

ParametersJSON Schema

Name	Required	Description	Default
`groupId`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention side effects, whether the operation is reversible, any permissions required, or what happens to the elements after ungrouping. It is a minimal statement of intent without behavioral depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, short sentence that immediately communicates the core action. It is concise, fully front-loaded, and contains no unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description is too sparse. It does not explain the required parameter, potential errors, or behavioral outcomes, leaving the agent with only a high-level understanding. More context is needed for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% coverage, and the description does not explain the 'groupId' parameter at all. While the parameter name is somewhat self-explanatory, the description adds no meaning beyond what the schema provides, failing to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Ungroup') and the target ('a group of elements'), making it immediately distinguishable from sibling tools like group_elements. The verb+resource structure is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, prerequisites (e.g., elements must already be grouped), or context for typical use cases. The description simply states the operation without any additional context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unlock_elementsB

Unlock elements to allow modification

ParametersJSON Schema

Name	Required	Description	Default
`elementIds`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It only states the basic action and purpose, but does not mention side effects, whether the operation is reversible, idempotency, or any required permissions. This is a significant gap for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the action and purpose, with no wasted words. Every part contributes to meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one parameter, no output schema), but given the absence of annotations, the description is too minimal. It does not clarify return behavior, effects on element state, or how it relates to lock_elements, leaving significant gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention the elementIds parameter at all. It neither explains the format, accepts one or multiple IDs, nor the type of elements. The description fails to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action with a specific verb ('Unlock') and resource ('elements'), and the phrase 'to allow modification' clarifies the purpose. It distinguishes itself from the sibling tool lock_elements by describing the inverse operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'to allow modification' implies the tool is used before modifying elements, giving some context. However, it lacks explicit guidance on when to use it versus alternatives like lock_elements or update_element, and no exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_elementC

Update an existing Excalidraw element

ParametersJSON Schema

Name	Required	Description	Default
`backgroundColor`	No
`fontFamily`	No
`fontSize`	No
`height`	No
`id`	Yes
`opacity`	No
`roughness`	No
`strokeColor`	No
`strokeWidth`	No
`text`	No
`type`	No
`width`	No
`x`	No
`y`	No

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool updates elements but doesn't describe what happens during the update (e.g., partial vs. full updates, error handling, permissions required, or rate limits). For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It's front-loaded with the core purpose and efficiently conveys the essential action and target. Every word earns its place, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (14 parameters, mutation tool), lack of annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like error conditions, return values, or usage context. While concise, it fails to provide sufficient context for effective tool selection and invocation in this environment.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides no information about parameters beyond what's implied by the tool name. With 14 parameters, 0% schema description coverage, and no output schema, the description fails to add any semantic context (e.g., explaining 'id' is required, what 'type' enum values mean, or how 'opacity' scales). This is inadequate given the high parameter count and low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update') and resource ('an existing Excalidraw element'), making the purpose immediately understandable. It distinguishes itself from siblings like 'create_element' and 'delete_element' by specifying it's for existing elements, though it doesn't explicitly contrast with similar tools like 'query_elements' or 'lock_elements'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an element ID), exclusions (e.g., not for new elements), or comparisons to siblings like 'create_element' for new elements or 'query_elements' for retrieval. Usage is implied but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

11 tool updatesv1.0.0May 14, 2025
- First observedalign_elements
- First observedcreate_element
- First observeddelete_element
- First observeddistribute_elements
- First observedget_resource
- First observedgroup_elements
- First observedlock_elements
- First observedquery_elements
- First observedungroup_elements
- First observedunlock_elements
- First observedupdate_element

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored 2026-04-18 11:15 across 11 tools

Disambiguation5/5

Every tool has a clearly distinct purpose focused on specific operations in Excalidraw, such as creation, deletion, alignment, distribution, grouping, locking, querying, and updating. There is no overlap or ambiguity between tools like 'create_element' and 'update_element' or 'lock_elements' and 'unlock_elements', making misselection unlikely.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case, such as 'create_element', 'delete_element', and 'group_elements'. The naming is predictable and readable throughout, with no deviations in style or convention.

Tool Count5/5

With 11 tools, the server is well-scoped for managing Excalidraw elements, covering essential operations like CRUD, grouping, alignment, and locking. Each tool earns its place without feeling excessive or insufficient for the domain.

Completeness5/5

The tool set provides complete coverage for Excalidraw element management, including full CRUD (create, query, update, delete), lifecycle operations (lock/unlock, group/ungroup), and layout utilities (align, distribute). There are no obvious gaps that would cause agent failures in this domain.

Maintenance

ActivityActive

ResponsivenessWithin a week

Resources

Need Help?

Reddit Discussion

Related Servers

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
mcp COAuth
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
216
irenictableOAuth
org.benevolabs
Collaborative whiteboard MCP server — create objects, connectors, C4 diagrams, and manage boards
Design Tools Workplace & Productivity Software Architecture
2
Sentry AOAuth
dev.sentry.mcp
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
Monitoring Developer Tools Observability
3

Related MCP Servers

Excalidraw MCP Server
Developer Tools App Automation Content Management Systems
i-tozer
A
license
A
quality
D
maintenance
A Model Context Protocol server that provides API functionality for creating, managing, and exporting Excalidraw drawings in various formats like SVG, PNG, and JSON.
Updated 2 years ago (2025-03-15 10:19 UTC)
8
2,464 npm
45
MIT
Mermaid MCP Server
Code Execution Developer Tools Documentation Access
longjianjiang
A
license
Not graded
quality
Not graded
maintenance
A server that implements the Model Context Protocol (MCP), providing an interface for LLM applications to generate mermaid.js visualizations and diagrams.
Updated a year ago (2025-03-26 16:57 UTC)
MIT
Excalidraw MCP Server
Autonomous Agents App Automation
Abdullah007bajwa
A
license
B
quality
D
maintenance
A Model Context Protocol server that enables LLMs to create, modify and manipulate Excalidraw diagrams through a structured API, supporting element creation, styling, organization, and scene management.
Updated a year ago (2025-04-20 01:45 UTC)
12
2,464 npm
MIT
drawio-mcp
Design Tools Software Architecture
Sujimoshi
A
license
Not graded
quality
C
maintenance
A Model Context Protocol server for creating and managing draw.io diagrams with batch operations and rich node types.
Updated a year ago (2025-09-22 19:45 UTC)
58 npm
31
Apache 2.0

Excalidraw MCP Server, CLI & Agent Skill

Demo

Table of Contents

What It Is

How We Differ from the Official Excalidraw MCP

What's New

v2.0 — Interchange-Grade Exports & MCP 2026-07-28

v1.1 — CLI-First

Installation

Easiest: let your agent install it

Manual install

60-Second Quick Start (CLI)

Agent Skill

CLI Reference

Configure MCP Clients

Environment Variables

Claude Desktop

Claude Code

Cursor

Codex CLI

OpenCode

Antigravity (Google)

Notes

MCP Tools (26 Total)

Quick Start (From Source / Docker)

Testing

CLI Smoke Test

Canvas Smoke Test (HTTP)

Local Bind Regression Test

Canvas Browser Regression Tests

MCP Stdio Wire Test

MCP Smoke Test (MCP Inspector)

Frontend Screenshots (agent-browser)

FAQ

How is this different from the official Excalidraw MCP?

Which AI tools does it work with?

Can the AI actually see the diagram it drew?

Do I need a browser open?

Are my diagrams persistent?

Are excalidraw.com share links private?

Does it need an API key or cloud service?

Can I use it without configuring MCP?

Troubleshooting

Known Issues / TODO

Development

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches