Skip to main content
Glama

Excalidraw MCP Server

npm version License: MIT

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-mcp

Codex CLI

codex mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcp

Cursor / Windsurf

Go to Settings > MCP โ†’ Add New MCP Server:

Field

Value

Name

excalidraw

Type

command

Command

npx -y @scofieldfree/excalidraw-mcp

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 add

Alternatively, 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-mcp

VS 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.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "@scofieldfree/excalidraw-mcp"]
    }
  }
}

๐Ÿ› ๏ธ Available Tools

Tool

Description

start_session

Start browser preview and open Excalidraw editor

add_elements

Add shapes, text, arrows to the canvas

update_element

Modify existing element properties

delete_element

Remove elements from canvas

get_scene

Retrieve current diagram state

create_from_mermaid

Convert Mermaid syntax to Excalidraw

add_template_architecture

Add a pre-built architecture diagram template

create_diagram

Create a new diagram or clear existing

export_diagram

Export diagram to PNG, SVG, or JSON

list_sessions

List all active diagram sessions

delete_diagram

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_mermaid

Example 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 dev

Scripts

Command

Description

pnpm dev

Start dev server (backend + frontend)

pnpm build

Build for production

pnpm typecheck

Run TypeScript type checking

pnpm lint

Run ESLint

pnpm release

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.

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'feat: add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request


๐Ÿ“œ License

MIT ยฉ Scofieldfree


Available Tools

11 tools
add_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:

  1. If a sessionId is specified, clear all elements in that session.

  2. If no sessionId is specified, create a new session.

  3. 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:

  1. Browser window opens automatically

  2. Excalidraw editor loads

  3. 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

    A4/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      8
      MIT