Excalidraw MCP Server
Enables AI agents to programmatically generate, edit, and view Excalidraw diagrams, featuring tools for adding shapes, text, and arrows with real-time preview and bi-directional synchronization.
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., "@Excalidraw MCP Server Create a flowchart showing how a user logs into our app"
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.
Excalidraw MCP Server
An MCP (Model Context Protocol) server that empowers AI agents (like Claude, Cursor, Windsurf) to create, edit, and manage Excalidraw diagrams directly within your conversation.
Why Excalidraw? Its hand-drawn aesthetic and JSON-based format are perfect for rapid, programmable diagramming. This server bridges standard MCP clients with a local Excalidraw instance, enabling AI-powered visual thinking.
โจ Features
Feature | Description |
๐จ Real-time Preview | Changes appear instantly in a local browser window via WebSocket |
๐ Smart Layout | Automatically calculates text width and binds labels to containers |
๐ Multi-Session | Switch between different diagrams seamlessly |
๐ง Mermaid Support | Convert Mermaid syntax to Excalidraw diagrams instantly |
๐ฆ Export Options | Export to PNG, SVG, or JSON formats |
๐๏ธ Templates | Built-in architecture diagram templates |
Related MCP server: Excalidraw MCP Server
๐ Quick Start
You don't need to clone this repo. Just configure your MCP client:
Claude Code (cc)
claude mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcpCodex CLI
codex mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcpCursor / Windsurf
Go to Settings > MCP โ Add New MCP Server:
Field | Value |
Name |
|
Type |
|
Command |
|
Cline (VS Code Extension)
Open Cline settings and add to MCP Servers:
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}GitHub Copilot
Use the Copilot CLI to interactively add:
/mcp addAlternatively, create or edit ~/.copilot/mcp-config.json:
{
"mcpServers": {
"excalidraw": {
"type": "local",
"command": "npx",
"tools": ["*"],
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}Kiro
Follow the MCP Servers documentation. Add to .kiro/settings/mcp.json:
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}opencode
opencode mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcpVS Code
One-click install:
Or install via CLI:
# For VS Code
code --add-mcp '{"name":"excalidraw","command":"npx","args":["-y","@scofieldfree/excalidraw-mcp"]}'
# For VS Code Insiders
code-insiders --add-mcp '{"name":"excalidraw","command":"npx","args":["-y","@scofieldfree/excalidraw-mcp"]}'Claude Desktop
Add to your claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}๐ ๏ธ Available Tools
Tool | Description |
| Start browser preview and open Excalidraw editor |
| Add shapes, text, arrows to the canvas |
| Modify existing element properties |
| Remove elements from canvas |
| Retrieve current diagram state |
| Convert Mermaid syntax to Excalidraw |
| Add a pre-built architecture diagram template |
| Create a new diagram or clear existing |
| Export diagram to PNG, SVG, or JSON |
| List all active diagram sessions |
| Delete a diagram session |
๐ฌ Usage Examples
Example 1: Create a Simple Diagram
You say:
"Draw a flowchart with three boxes: Input โ Process โ Output"
AI uses:
start_session โ add_elements (3 rectangles + 2 arrows)Example 2: Convert Mermaid to Excalidraw
You say:
"Convert this Mermaid diagram to Excalidraw:
graph LR: A[User] --> B[API Gateway] --> C[Service] --> D[(Database)]"
AI uses:
start_session โ create_from_mermaidExample 3: Architecture Diagram
You say:
"Create an architecture diagram for a microservices system"
AI uses:
start_session โ add_template_architecture (or) add_elements with custom layout๐๏ธ Architecture
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ AI Agent (Claude/Cursor) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ MCP Protocol (JSON-RPC over stdio)
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Excalidraw MCP Server โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Tool Router โโโโ State Store โโโโ WebSocket Broadcast โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโฌโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโ
โ WebSocket
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Browser (Excalidraw Editor) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ๐ง Development
Prerequisites
Node.js >= 18
pnpm >= 9
Setup
# Clone the repository
git clone https://github.com/Scofieldfree/excalidraw-mcp.git
cd excalidraw-mcp
# Install dependencies
pnpm install
# Start development server
pnpm devScripts
Command | Description |
| Start dev server (backend + frontend) |
| Build for production |
| Run TypeScript type checking |
| Run ESLint |
| Create a new release version |
๐ฆ Project Structure
excalidraw-mcp/
โโโ packages/
โ โโโ mcp-server/ # Core MCP server + Excalidraw frontend
โ โโโ src/
โ โ โโโ index.ts # Entry point
โ โ โโโ state.ts # Session state management
โ โ โโโ http-server.ts
โ โ โโโ tools/ # MCP tool implementations
โ โโโ web/ # Excalidraw React frontend
โโโ docs/ # Documentation
โโโ package.json # Workspace configuration๐ Troubleshooting
Port Already in Use
The server automatically finds an available port starting from 3100. If you need a specific port, set the PORT environment variable.
Browser Doesn't Open
Ensure you have a default browser configured. The server uses the open package to launch the browser.
WebSocket Connection Failed
Check if any firewall or antivirus is blocking WebSocket connections on localhost.
๐ค Contributing
Contributions are welcome! Please read our Contributing Guide for details.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'feat: add amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
๐ License
MIT ยฉ Scofieldfree
๐ Links
Available Tools
11 toolsadd_elementsA
Add multiple Excalidraw elements to the canvas.
Supported element types:
rectangle
ellipse
diamond
arrow
text
line
freedraw
image
frame/magicframe
iframe/embeddable
Style options:
strokeColor: e.g. #1e1e1e
backgroundColor: e.g. #D97706
fillStyle: solid/hachure/cross-hatch
strokeWidth: 1-4
roughness: 0=architect, 1=artist, 2=cartoonist
Advanced options:
label: Auto-create bound text inside shape/arrow containers
start/end: Arrow endpoint binding to new or existing elements
containerId: DEPRECATED (use label instead)
Multi-session support: Specify sessionId to target a specific session.
Inputs: elements (required), sessionId.
add_template_architectureA
Add a built-in architecture diagram template to the canvas.
This template visualizes the MCP server architecture with grouped layers and connected arrows. By default it resets the current session before adding template elements.
Inputs: sessionId, reset.
create_diagramA
Create a new diagram or clear an existing session.
This action will:
If a sessionId is specified, clear all elements in that session.
If no sessionId is specified, create a new session.
Reset the application state.
Usage scenarios: โข Starting a new project (no sessionId specified) โข Clearing an existing diagram (sessionId specified) โข Creating multiple independent diagrams (specify different sessionIds each time)
Inputs: sessionId, viewBackgroundColor.
create_from_mermaidA
Create diagram elements from Mermaid syntax.
Converts Mermaid text to Excalidraw elements through connected browser client. If browser is not connected yet, request is queued and sent after websocket ready. Returns clear errors for timeout and mermaid syntax problems.
Inputs: mermaidDiagram (required), sessionId, reset.
delete_diagramA
Delete the specified diagram session.
Note: This will completely delete the session and all its elements, and cannot be undone. If you only want to clear elements but keep the session, use create_diagram and specify the sessionId.
Inputs: sessionId (required).
delete_elementA
Delete a specific element from the canvas.
Usage scenarios:
Remove unwanted elements
Clean up temporary elements
Delete erroneously added elements
Multi-session support: Specify sessionId to target a specific session.
Inputs: id (required), sessionId.
export_diagramA
Export the current diagram to a PNG, SVG, or JSON file.
Notes:
JSON format is saved directly by the server.
PNG/SVG are generated by the browser and sent back to the server to save.
Requires start_session to be called first and the browser to be connected.
Multi-session support: Specify sessionId to target a specific session.
Inputs: path (required), sessionId, format.
get_sceneA
Retrieve complete information about the current diagram scene.
Returns:
List of all elements
Application state
Version number
Session ID
Usage scenarios:
Viewing current diagram content
Analyzing scene structure
Obtaining element IDs for updates/deletion
Multi-session support: Specify sessionId to query a specific session.
Inputs: sessionId.
list_sessionsA
List all currently active Excalidraw sessions.
Inputs: no named parameters.
start_sessionA
Start browser preview and open Excalidraw editor interface.
Multi-session support:
No sessionId: Uses default session (default)
sessionId specified: Open/Create specific session
Multiple sessions can be opened simultaneously for different diagrams
After calling this tool:
Browser window opens automatically
Excalidraw editor loads
WebSocket realtime connection is established
Please pass the same sessionId when using tools like add_elements, update_element subsequently.
Inputs: sessionId.
update_elementA
Update attributes of an existing element.
Updatable attributes:
x, y: Position coordinates
width, height: Dimensions
strokeColor: Stroke color
backgroundColor: Background color
fillStyle: Fill style
strokeWidth: Stroke width
roughness: Roughness
opacity: Opacity
text: Text content (only for text type)
Multi-session support: Specify sessionId to target a specific session.
Inputs: id (required), updates (required), sessionId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 11 tools
Most tools have distinct purposes (adding, deleting, exporting, querying). However, 'add_elements' and 'create_from_mermaid' both add elements, though via different inputs, and 'add_template_architecture' is a specialized add. Descriptions help distinguish them, so minor ambiguity exists.
Tool names largely follow a verb_noun pattern (e.g., 'add_elements', 'delete_diagram'). 'create_from_mermaid' breaks this pattern by including a preposition, causing slight inconsistency. Otherwise consistent.
With 11 tools covering diagram creation, manipulation, querying, export, and session management, the count is well-scoped for the domain. Each tool serves a clear purpose without redundancy.
Core operations (create, read, update, delete elements and sessions, export) are covered. Minor gaps like undo/redo or advanced layout operations are absent but not critical for typical use.
Maintenance
Related MCP Connectors
Create, edit and organize hand-drawn diagrams (flowcharts, ER, architecture) from any AI agent.
A shared Excalidraw board that people and agents draw on together
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Draw architecture diagrams, UML, planning boards and clickable wireframes from your AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to programmatically control a live Excalidraw canvas through element-level CRUD operations and real-time synchronization. It allows agents to iteratively build, inspect, and refine diagrams while providing visual feedback via screenshots and scene descriptions.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to programmatically control a live Excalidraw canvas with element-level CRUD operations and real-time synchronization. It supports iterative diagramming through scene descriptions, screenshots, and advanced layout tools for collaborative AI-human workflows.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, modify, and share diagrams on a live Excalidraw canvas through MCP tools, supporting shapes, text, arrows, batch operations, and export to shareable links with images.5,646 npm8MIT
- AlicenseAqualityDmaintenanceEnables AI agents to generate and edit draw.io diagrams with real-time browser preview.559 npmApache 2.0