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

🚀 Quick Start

You don't need to clone this repo. Just configure your MCP client:

Claude Code (cc)

bashCopy code
claude mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcp

Codex CLI

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

Cursor / Windsurf

Go to Settings > MCP → Add New MCP Server:

Cline (VS Code Extension)

Open Cline settings and add to MCP Servers:

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

GitHub Copilot

Use the Copilot CLI to interactively add:

bashCopy code
/mcp add

Alternatively, create or edit ~/.copilot/mcp-config.json:

jsonCopy code
{
  "mcpServers": {
    "excalidraw": {
      "type": "local",
      "command": "npx",
      "tools": ["*"],
      "args": ["-y", "@scofieldfree/excalidraw-mcp"]
    }
  }
}

Kiro

Follow the MCP Servers documentation. Add to .kiro/settings/mcp.json:

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

opencode

bashCopy code
opencode mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcp

VS Code

One-click install:

Or install via CLI:

bashCopy code
# 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

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

🛠️ Available Tools

💬 Usage Examples

Example 1: Create a Simple Diagram

You say:

"Draw a flowchart with three boxes: Input → Process → Output"

AI uses:

Copy code
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:

Copy code
start_session → create_from_mermaid

Example 3: Architecture Diagram

You say:

"Create an architecture diagram for a microservices system"

AI uses:

Copy code
start_session → add_template_architecture (or) add_elements with custom layout

🏗️ Architecture

Copy code
┌─────────────────────────────────────────────────────────────┐
│                     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

bashCopy code
# 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

📦 Project Structure

Copy code
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

🔗 Links

• npm Package
• GitHub Repository
• Excalidraw
• Model Context Protocol