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)

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:

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

---

💬 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

---

📦 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

---

🔗 Links

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