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