MCP Excalidraw Server: Advanced Live Visual Diagramming with AI Integration

A comprehensive TypeScript-based system that combines Excalidraw's powerful drawing capabilities with Model Context Protocol (MCP) integration, enabling AI agents to create and manipulate diagrams in real-time on a live canvas.

🚦 Current Status & Version Information

📋 Choose Your Installation Method

Important: Canvas and MCP Server Run Separately

This system consists of two independent components:

1. Canvas Server - Runs the live Excalidraw canvas (web interface)
2. MCP Server - Connects to Claude Desktop/Claude Code/Cursor IDE

You can choose any combination:

• Canvas: Local OR Docker
• MCP Server: Local OR Docker

Both local and Docker setups are fully working and production-ready!

🚀 What This System Does

• 🎨 Live Canvas: Real-time Excalidraw canvas accessible via web browser
• 🤖 AI Integration: MCP server allows AI agents (like Claude) to create visual diagrams
• ⚡ Real-time Sync: Elements created via MCP API appear instantly on the canvas
• 🔄 WebSocket Updates: Live synchronization across multiple connected clients
• 🏗️ Production Ready: Clean, minimal UI suitable for end users

🎥 Demo Video

See MCP Excalidraw in Action!

Watch how AI agents create and manipulate diagrams in real-time on the live canvas

🏛️ Architecture Overview

Two Independent Components

┌─────────────────────────────────────────────────────────────────┐
│                         Component 1                              │
│                     🎨 CANVAS SERVER                             │
│                   (Runs Independently)                           │
│                                                                  │
│  ┌─────────────────┐         ┌─────────────────┐               │
│  │  Canvas Server  │◀───────▶│   Frontend      │               │
│  │ (src/server.js) │         │  (React + WS)   │               │
│  │  Port 3000      │         │  Excalidraw UI  │               │
│  └─────────────────┘         └─────────────────┘               │
│                                                                  │
│  📍 Start: npm run canvas  OR  docker run (canvas)              │
└─────────────────────────────────────────────────────────────────┘

                              ▲
                              │ HTTP API
                              │ (Optional)
                              │
┌─────────────────────────────────────────────────────────────────┐
│                         Component 2                              │
│                      🤖 MCP SERVER                               │
│                   (Runs Independently)                           │
│                                                                  │
│  ┌─────────────────┐         ┌─────────────────┐               │
│  │   AI Agent      │◀───────▶│   MCP Server    │               │
│  │   (Claude)      │         │ (src/index.js)  │               │
│  │  Desktop/Code   │  stdio  │  MCP Protocol   │               │
│  └─────────────────┘         └─────────────────┘               │
│                                                                  │
│  📍 Configure in: claude_desktop_config.json OR .mcp.json       │
└─────────────────────────────────────────────────────────────────┘

🎯 Key Points:
• Canvas and MCP server are SEPARATE processes
• Canvas can run locally OR in Docker
• MCP server can run locally OR in Docker
• Canvas provides the visual interface (optional)
• MCP server connects Claude to the canvas (via HTTP API)

🌟 Key Features

Modern TypeScript Architecture

• Full TypeScript Migration: Complete type safety for backend and frontend
• Comprehensive Type Definitions: Excalidraw elements, API responses, WebSocket messages
• Strict Type Checking: Enhanced development experience and compile-time error detection
• Type-Safe React Components: TSX components with proper props typing

🎨 Mermaid Diagram Support (NEW!)

• Mermaid to Excalidraw: Convert Mermaid diagrams directly to Excalidraw elements
• MCP Tool Integration: Use create_from_mermaid tool from Claude
• Browser-based Conversion: Leverages DOM access in the frontend for accurate rendering
• Multiple Diagram Types: Supports flowcharts, sequence diagrams, class diagrams, and more
• Test Button: Quick test functionality directly from the canvas UI

Real-time Canvas Integration

• Elements created via MCP appear instantly on the live canvas
• WebSocket-based real-time synchronization
• Multi-client support with live updates

Production-Ready Interface

• Clean, minimal UI with connection status
• Simple "Clear Canvas" functionality
• No development clutter or debug information

Comprehensive MCP API

• Element Creation: rectangles, ellipses, diamonds, arrows, text, lines
• Element Management: update, delete, query with filters
• Batch Operations: create multiple elements in one call
• Advanced Features: grouping, alignment, distribution, locking

Robust Architecture

• TypeScript-based Express.js backend with REST API + WebSocket
• React frontend with official Excalidraw package and TypeScript
• Dual-path element loading for reliability
• Auto-reconnection and error handling

📦 Installation & Setup

Step 1: Choose Your Canvas Server Setup

The canvas server provides the live Excalidraw interface.

Option A: Local Canvas Server

1. Clone and Install

git clone https://github.com/yctimlin/mcp_excalidraw.git
cd mcp_excalidraw
npm install

2. Build the Project

npm run build

3. Start Canvas Server

# Production mode (recommended)
npm run canvas

4. Access the Canvas

http://localhost:3000

Option B: Docker Canvas Server

Option B1: Use Pre-built Image from GHCR (Recommended)

docker pull ghcr.io/yctimlin/mcp_excalidraw-canvas:latest
docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest

Option B2: Build Locally

git clone https://github.com/yctimlin/mcp_excalidraw.git
cd mcp_excalidraw
docker build -f Dockerfile.canvas -t mcp-excalidraw-canvas .
docker run -d -p 3000:3000 --name mcp-excalidraw-canvas mcp-excalidraw-canvas

3. Access the Canvas

http://localhost:3000

---

Step 2: Configure MCP Server in Your IDE

The MCP server connects your AI assistant (Claude) to the canvas. Choose local OR Docker format based on your preference.

Setup Combinations

You can mix and match any combination:

Configuration examples are provided in the next section for:

• Claude Desktop
• Claude Code
• Cursor IDE

🔧 Available Scripts

🎯 Usage Guide

For End Users

1. Open the canvas at http://localhost:3000
2. Check connection status (should show "Connected")
3. AI agents can now create diagrams that appear in real-time
4. Use "Clear Canvas" to remove all elements

For AI Agents (via MCP)

The MCP server provides these tools for creating visual diagrams:

Basic Element Creation

// Create a rectangle
{
  "type": "rectangle",
  "x": 100,
  "y": 100, 
  "width": 200,
  "height": 100,
  "backgroundColor": "#e3f2fd",
  "strokeColor": "#1976d2",
  "strokeWidth": 2
}

Create Text Elements

{
  "type": "text",
  "x": 150,
  "y": 125,
  "text": "Process Step",
  "fontSize": 16,
  "strokeColor": "#333333"
}

Create Arrows & Lines

{
  "type": "arrow",
  "x": 300,
  "y": 130,
  "width": 100,
  "height": 0,
  "strokeColor": "#666666",
  "strokeWidth": 2
}

Batch Creation for Complex Diagrams

{
  "elements": [
    {
      "type": "rectangle",
      "x": 100,
      "y": 100,
      "width": 120,
      "height": 60,
      "backgroundColor": "#fff3e0",
      "strokeColor": "#ff9800"
    },
    {
      "type": "text", 
      "x": 130,
      "y": 125,
      "text": "Start",
      "fontSize": 16
    }
  ]
}

🔌 MCP Server Configuration for IDEs

Prerequisites

✅ Ensure your canvas server is running (from Step 1):

• Local: npm run canvas
• Docker: docker run -d -p 3000:3000 mcp-excalidraw-canvas

Canvas should be accessible at http://localhost:3000

Quick Reference

Choose your configuration based on IDE and preference:

⭐ = Recommended | ✅ = Fully Working

---

Configuration for Claude Desktop

Edit your claude_desktop_config.json file:

Format 1: Local MCP Server ⭐ Recommended

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://localhost:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

Important: Replace /absolute/path/to/mcp_excalidraw with your actual installation path.

Format 2: Docker MCP Server ✅ Fully Working

Using Pre-built Image from GHCR (Recommended):

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "host",
        "-e", "EXPRESS_SERVER_URL=http://localhost:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

OR Build Locally:

cd mcp_excalidraw
docker build -f Dockerfile -t mcp-excalidraw .

Then use mcp-excalidraw as the image name in the configuration above.

---

Configuration for Claude Code

Create or edit .mcp.json in your project root:

Format 1: Local MCP Server ⭐ Recommended

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://localhost:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

Important: Replace /absolute/path/to/mcp_excalidraw with your actual installation path.

Format 2: Docker MCP Server ✅ Fully Working

Using Pre-built Image from GHCR (Recommended):

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "host",
        "-e", "EXPRESS_SERVER_URL=http://localhost:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

OR Build Locally:

cd mcp_excalidraw
docker build -f Dockerfile -t mcp-excalidraw .

Then use mcp-excalidraw as the image name in the configuration above.

Alternative: Using Claude CLI

# Project-scoped (recommended)
claude mcp add --scope project --transport stdio excalidraw \
  -- docker run -i --rm --network host \
  -e EXPRESS_SERVER_URL=http://localhost:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  mcp-excalidraw

# User-scoped (available across all projects)
claude mcp add --scope user --transport stdio excalidraw \
  -- docker run -i --rm --network host \
  -e EXPRESS_SERVER_URL=http://localhost:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  mcp-excalidraw

---

Configuration for Cursor IDE

Edit .cursor/mcp.json:

Format 1: Local MCP Server ⭐ Recommended

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://localhost:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

Format 2: Docker MCP Server ✅ Fully Working

Using Pre-built Image from GHCR (Recommended):

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "host",
        "-e", "EXPRESS_SERVER_URL=http://localhost:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

OR Build Locally:

cd mcp_excalidraw
docker build -f Dockerfile -t mcp-excalidraw .

Then use mcp-excalidraw as the image name in the configuration above.

---

Important Configuration Notes

Canvas is optional: The MCP server works without the canvas in API-only mode (for programmatic access only).

🛠️ Environment Variables

📊 API Endpoints

The canvas server provides these REST endpoints:

🎨 MCP Tools Available

Element Management

• create_element - Create any type of Excalidraw element
• update_element - Modify existing elements
• delete_element - Remove elements
• query_elements - Search elements with filters

Batch Operations

• batch_create_elements - Create complex diagrams in one call

Element Organization

• group_elements - Group multiple elements
• ungroup_elements - Ungroup element groups
• align_elements - Align elements (left, center, right, top, middle, bottom)
• distribute_elements - Distribute elements evenly
• lock_elements / unlock_elements - Lock/unlock elements

Resource Access

• get_resource - Access scene, library, theme, or elements data

🏗️ Development Architecture

Frontend (frontend/src/)

• React + TypeScript: Modern TSX components with full type safety
• Vite Build System: Fast development and optimized production builds
• Official Excalidraw: @excalidraw/excalidraw package with TypeScript types
• WebSocket Client: Type-safe real-time element synchronization
• Clean UI: Production-ready interface with proper TypeScript typing

Canvas Server (src/server.ts → dist/server.js)

• TypeScript + Express.js: Fully typed REST API + static file serving
• WebSocket: Type-safe real-time client communication
• Element Storage: In-memory with comprehensive type definitions
• CORS: Cross-origin support with proper typing

MCP Server (src/index.ts → dist/index.js)

• TypeScript MCP Protocol: Type-safe Model Context Protocol implementation
• Canvas Sync: Strongly typed HTTP requests to canvas server
• Element Management: Full CRUD operations with comprehensive type checking
• Batch Support: Type-safe complex diagram creation

Type System (src/types.ts)

• Excalidraw Element Types: Complete type definitions for all element types
• API Response Types: Strongly typed REST API interfaces
• WebSocket Message Types: Type-safe real-time communication
• Server Element Types: Enhanced element types with metadata

🐛 Troubleshooting

Canvas Not Loading

• Ensure npm run build completed successfully
• Check that dist/index.html and dist/frontend/ directory exist
• Verify canvas server is running on port 3000
• Check if port 3000 is already in use: lsof -i :3000 (macOS/Linux) or netstat -ano | findstr :3000 (Windows)

Elements Not Syncing

• Confirm canvas server is running and accessible at http://localhost:3000
• Check ENABLE_CANVAS_SYNC=true in MCP server environment configuration
• Verify EXPRESS_SERVER_URL points to correct canvas server URL
• Check browser console for WebSocket connection errors
• For Docker: Ensure --network host flag is used

WebSocket Connection Issues

• Check browser console for WebSocket errors (F12 → Console tab)
• Ensure no firewall blocking WebSocket connections on port 3000
• Try refreshing the browser page
• Verify canvas server is running: curl http://localhost:3000/health

Docker Issues

Canvas Container:

• Check if container is running: docker ps | grep canvas
• View logs: docker logs mcp-excalidraw-canvas
• Ensure port 3000 is not already in use

MCP Container:

• For Docker MCP server, ensure --network host is used (required to access localhost:3000)
• Verify -i flag is present (required for MCP stdin/stdout protocol)
• Check environment variables are properly set

Build Errors

• Delete node_modules and dist/ directories, then run npm install && npm run build
• Check Node.js version (requires 16+): node --version
• Run npm run type-check to identify TypeScript issues
• Verify dist/ directory contains both index.js, server.js, and frontend/ after build

NPM Package Issues

• Status: NPM package is under development
• Recommendation: Use local or Docker installation methods for production use

📋 Project Structure

mcp_excalidraw/
├── frontend/
│   ├── src/
│   │   ├── App.tsx          # Main React component (TypeScript)
│   │   └── main.tsx         # React entry point (TypeScript)
│   └── index.html           # HTML template
├── src/ (TypeScript Source)
│   ├── index.ts            # MCP server (TypeScript)
│   ├── server.ts           # Canvas server (Express + WebSocket, TypeScript)
│   ├── types.ts            # Comprehensive type definitions
│   └── utils/
│       └── logger.ts       # Logging utility (TypeScript)
├── dist/ (Compiled Output)
│   ├── index.js            # Compiled MCP server
│   ├── server.js           # Compiled Canvas server
│   ├── types.js            # Compiled type definitions
│   ├── utils/
│   │   └── logger.js       # Compiled logging utility
│   └── frontend/           # Built React frontend
├── tsconfig.json          # TypeScript configuration
├── vite.config.js         # Vite build configuration
├── package.json           # Dependencies and scripts
└── README.md              # This file

🔮 Development Roadmap

• ✅ TypeScript Migration: Complete type safety for enhanced development experience
• ✅ Docker Deployment: Both Canvas and MCP server fully working in Docker
• 🔧 NPM Package: Resolving MCP tool registration issues
• 🎯 Enhanced Features: Additional MCP tools and capabilities
• 🎯 Performance Optimization: Real-time sync improvements
• 🎯 Advanced TypeScript Features: Stricter type checking and advanced type utilities
• 🎯 Container Registry: Publishing to GitHub Container Registry (GHCR)

🤝 Contributing

We welcome contributions! If you're experiencing issues with the NPM package or Docker version, please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Excalidraw Team - For the amazing drawing library
• MCP Community - For the Model Context Protocol specification