align_elements
Align elements to a specific position
LABSCO SUMMARY
The agent draws, then looks at what it drew.
What it takes off you is describing the picture back to it. The scene description and the canvas screenshot let the model check its own diagram before adding to it, and arrows bound by element id stay attached through the moves that would otherwise leave them pointing at nothing.
What it is
An Excalidraw canvas driven as a scene, with 26 tools. Elements are created singly or in batches, arrows bind to shapes by id, and the agent can read the scene back — as a description or as a screenshot — before changing it.
What you get
- Elements created, read, updated, deleted and queried, in batches and duplicated at an offset (
create_element,get_element,update_element,delete_element,query_elements,batch_create_elements,duplicate_elements) - Layout operations: align, distribute evenly, group and ungroup, lock and unlock (
align_elements,distribute_elements,group_elements,ungroup_elements,lock_elements,unlock_elements) - The scene read back as a description — types, positions, connections and labels — or as a canvas screenshot (
describe_scene,get_canvas_screenshot) - A Mermaid diagram converted into Excalidraw elements on the canvas (
create_from_mermaid) - Export to
.excalidrawJSON, to PNG or SVG, or to a shareable excalidraw.com URL, and import back from a file (export_scene,export_to_image,export_to_excalidraw_url,import_scene) - Named snapshots of the canvas and a restore, plus a clear (
snapshot_scene,restore_snapshot,clear_canvas) - Viewport control: fit everything, centre on one element, or zoom to fit a set of ids with a zoom factor (
set_viewport) - A design guide covering palette, sizing, layout patterns and arrow binding (
read_diagram_guide)
Requirements
Npx. Creating, querying and updating elements and exporting .excalidraw JSON all work headless; screenshots, PNG and SVG export, viewport control and Mermaid conversion render in the Excalidraw frontend, so they need the canvas open in a browser — the CLI exits with code 4 and says so when that is what is missing. The canvas is in-memory by design, so a restart is a blank canvas: export a .excalidraw file into your repo, or take named snapshots while you work. EXCALIDRAW_EXPORT_DIR bounds where file exports may be written, and EXPRESS_SERVER_URL points at the canvas server, http://127.0.0.1:3000 by default.
Setup effort
One command — npx -y mcp-excalidraw-server
USE CASES
01
Turning an architecture you described into a diagram
Batch-create the boxes, bind the arrows to them by id, then read the scene back to check it says what you meant. The design guide is worth reading first — it covers sizing, palette and the arrow-binding patterns that stop a diagram falling apart later.
02
Getting a Mermaid diagram onto a real canvas
Convert the Mermaid you already have into Excalidraw elements, then move things where they belong. It needs the canvas open in a browser, because the conversion renders in the frontend.
03
Tidying a diagram that grew messy
Align and distribute rather than nudging by hand, group what belongs together, and lock what you do not want moved again.
04
Checking the drawing actually reads
Take a canvas screenshot and look at it. A diagram that is structurally correct and visually unreadable is a common failure, and this is the call that catches it.
05
Keeping the diagram after you close the tab
The canvas is in-memory, so export a .excalidraw file into the repository and re-import it next time. Snapshots cover the shorter horizon while you are still working.
06
Sharing the result
Export to PNG or SVG for a document, or to an excalidraw.com URL for someone who wants to edit it. Both render in the frontend, so keep the browser tab open for these.
26 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
batch_create_elements
Create multiple Excalidraw elements at once. For arrows, use startElementId/endElementId to bind arrows to shapes — Excalidraw auto-routes to element edges. Assign custom id to shapes so arrows can reference them.
clear_canvas
Clear all elements from the canvas
create_element
Create a new Excalidraw element. For arrows, use startElementId/endElementId to bind to shapes (auto-routes to edges).
create_from_mermaid
Convert a Mermaid diagram to Excalidraw elements and render them on the canvas
delete_element
Delete an Excalidraw element
describe_scene
Get an AI-readable description of the current canvas: element types, positions, connections, labels, spatial layout, and bounding box. Use this to understand what is on the canvas before making changes.
distribute_elements
Distribute elements evenly
duplicate_elements
Duplicate elements with a configurable offset
export_scene
Export the current canvas to .excalidraw JSON format. Optionally write to a file.
export_to_excalidraw_url
Export the current canvas to a shareable excalidraw.com URL. The diagram is encrypted and uploaded; anyone with the URL can view it. Returns the shareable link.
export_to_image
Export the current canvas to PNG or SVG image. Requires the canvas frontend to be open in a browser.
get_canvas_screenshot
Take a screenshot of the current canvas and return it as an image. Requires the canvas frontend to be open in a browser. Use this to visually verify what the diagram looks like.
get_element
Get a single Excalidraw element by ID
get_resource
Get an Excalidraw resource
group_elements
Group multiple elements together
import_scene
Import elements from a .excalidraw JSON file or raw JSON data
lock_elements
Lock elements to prevent modification
query_elements
Query Excalidraw elements with optional filters
read_diagram_guide
Returns a comprehensive design guide for creating beautiful Excalidraw diagrams: color palette, sizing rules, layout patterns, arrow binding best practices, diagram templates, and anti-patterns. Call this before creating diagrams to produce professional results.
restore_snapshot
Restore the canvas from a previously saved named snapshot
set_viewport
Control the canvas viewport (camera). Auto-fit all elements, center on a specific element, or set zoom/scroll directly. Requires the canvas frontend open in a browser.
snapshot_scene
Save a named snapshot of the current canvas state for later restoration
ungroup_elements
Ungroup a group of elements
unlock_elements
Unlock elements to allow modification
update_element
Update an existing Excalidraw element
BEFORE YOU INSTALL
What to know first
Tools you get
26 tools when we connected. create_view belongs to the separate official Excalidraw MCP, not this server, and the CLI verbs such as add, apply and screenshot are not MCP tools.
Requires
npx on PATH
Where it runs
All 6 documented clients run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 26 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx -y mcp-excalidraw-serverMCP Clients
Claude Desktop, Cursor, Antigravity
JSON
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": [
"-y",
"mcp-excalidraw-server"
]
}
}
}Claude Code
CLAUDE CODE · TERMINAL
claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-serverCodex
CODEX · TERMINAL
codex mcp add excalidraw -- npx -y mcp-excalidraw-serverOpenCode
OPENCODE · JSON
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"excalidraw": {
"type": "local",
"command": [
"npx",
"-y",
"mcp-excalidraw-server"
],
"enabled": true
}
}
}
