Which integrations are available for this 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.

How do I use Excalidraw MCP Server?

1. Click on "Install 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 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

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

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

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

Excalidraw MCP Server

Excalidraw MCP Server

✨ Features

🚀 Quick Start

Claude Code (cc)

Codex CLI

Cursor / Windsurf

Cline (VS Code Extension)

GitHub Copilot

Kiro

opencode

VS Code

Claude Desktop

🛠️ Available Tools

💬 Usage Examples

Example 1: Create a Simple Diagram

Example 2: Convert Mermaid to Excalidraw

Example 3: Architecture Diagram

🏗️ Architecture

🔧 Development

Prerequisites

Setup

Scripts

📦 Project Structure

🐛 Troubleshooting

Port Already in Use

Browser Doesn't Open

WebSocket Connection Failed

🤝 Contributing

📜 License

🔗 Links

Resources

Tools

Latest Blog Posts

MCP directory API