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

Component	Local	Docker	Status
Canvas Server	✅ Fully Working	✅ Fully Working	Production Ready
MCP Server	✅ Fully Working	✅ Fully Working	Production Ready
NPM Published	🔧 In Progress	N/A	Development testing

Important: Canvas and MCP Server Run Separately

This system consists of two independent components:

Canvas Server - Runs the live Excalidraw canvas (web interface)
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

Clone and Install

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

Build the Project

npm run build

Start Canvas Server

# Production mode (recommended)
npm run canvas

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

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:

Canvas Server	MCP Server	Status
✅ Local	✅ Local	Recommended
✅ Local	✅ Docker	Fully Working
✅ Docker	✅ Local	Fully Working
✅ Docker	✅ Docker	Fully Working

Configuration examples are provided in the next section for:

Claude Desktop
Claude Code
Cursor IDE

🔧 Available Scripts

Script	Description
`npm start`	Build and start MCP server (`dist/index.js`)
`npm run canvas`	Build and start canvas server (`dist/server.js`)
`npm run build`	Build both frontend and TypeScript backend
`npm run build:frontend`	Build React frontend only
`npm run build:server`	Compile TypeScript backend to JavaScript
`npm run dev`	Start TypeScript watch mode + Vite dev server
`npm run type-check`	Run TypeScript type checking without compilation
`npm run production`	Build + start in production mode

🎯 Usage Guide

For End Users

Open the canvas at http://localhost:3000
Check connection status (should show "Connected")
AI agents can now create diagrams that appear in real-time
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:

IDE	Config File	Format Options
Claude Desktop	`claude_desktop_config.json`	Local ⭐ / Docker ✅
Claude Code	`.mcp.json` (project root)	Local ⭐ / Docker ✅
Cursor	`.cursor/mcp.json`	Local ⭐ / Docker ✅

⭐ = 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

Setting	Purpose	Required
`EXPRESS_SERVER_URL`	Canvas server URL	Yes (default: http://localhost:3000)
`ENABLE_CANVAS_SYNC`	Enable real-time canvas sync	Yes (set to "true")
`--network host`	Docker access to localhost	Required for Docker
`-i` flag	Interactive stdin/stdout	Required for Docker

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

🛠️ Environment Variables

Variable	Default	Description
`EXPRESS_SERVER_URL`	`http://localhost:3000`	Canvas server URL for MCP sync
`ENABLE_CANVAS_SYNC`	`true`	Enable/disable canvas synchronization
`LOG_FILE_PATH`	`excalidraw.log`	Path to the log file
`DEBUG`	`false`	Enable debug logging
`PORT`	`3000`	Canvas server port
`HOST`	`localhost`	Canvas server host

📊 API Endpoints

The canvas server provides these REST endpoints:

Method	Endpoint	Description
`GET`	`/api/elements`	Get all elements
`POST`	`/api/elements`	Create new element
`PUT`	`/api/elements/:id`	Update element
`DELETE`	`/api/elements/:id`	Delete element
`POST`	`/api/elements/batch`	Create multiple elements
`GET`	`/health`	Server health check

🎨 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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Excalidraw

MCP Excalidraw Server: Advanced Live Visual Diagramming with AI Integration

🚦 Current Status & Version Information

Important: Canvas and MCP Server Run Separately

🚀 What This System Does

🎥 Demo Video

🏛️ Architecture Overview

Two Independent Components

🌟 Key Features

Modern TypeScript Architecture

🎨 Mermaid Diagram Support (NEW!)

Real-time Canvas Integration

Production-Ready Interface

Comprehensive MCP API

Robust Architecture

📦 Installation & Setup

Step 1: Choose Your Canvas Server Setup

Option A: Local Canvas Server

Option B: Docker Canvas Server

Step 2: Configure MCP Server in Your IDE

Setup Combinations

🔧 Available Scripts

🎯 Usage Guide

For End Users

For AI Agents (via MCP)

Basic Element Creation

Create Text Elements

Create Arrows & Lines

Batch Creation for Complex Diagrams

🔌 MCP Server Configuration for IDEs

Prerequisites

Quick Reference

Configuration for Claude Desktop

Format 1: Local MCP Server ⭐ Recommended

Format 2: Docker MCP Server ✅ Fully Working

Configuration for Claude Code

Format 1: Local MCP Server ⭐ Recommended

Format 2: Docker MCP Server ✅ Fully Working

Alternative: Using Claude CLI

Configuration for Cursor IDE

Format 1: Local MCP Server ⭐ Recommended

Format 2: Docker MCP Server ✅ Fully Working

Important Configuration Notes

🛠️ Environment Variables

📊 API Endpoints

🎨 MCP Tools Available

Element Management

Batch Operations

Element Organization

Resource Access

🏗️ Development Architecture

Frontend (frontend/src/)

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

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

Type System (src/types.ts)

🐛 Troubleshooting

Canvas Not Loading

Elements Not Syncing

WebSocket Connection Issues

Docker Issues

Build Errors

NPM Package Issues

📋 Project Structure

🔮 Development Roadmap

🤝 Contributing

📝 License

🙏 Acknowledgments

Related MCP Server Picks for You

Be the First to Experience Cortex App

Frontend (`frontend/src/`)

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

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

Type System (`src/types.ts`)