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.

📋 Choose Your Installation Method

For the most stable experience, we recommend using the local development setup. We're actively working on improving the NPM package and Docker deployment options.

• NPM Package: Currently debugging MCP tool registration issues
• Docker Version: Improving canvas synchronization reliability
• Local Version: ✅ All features fully functional

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

See MCP Excalidraw in Action!

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

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agent      │───▶│   MCP Server     │───▶│  Canvas Server  │
│   (Claude)      │    │  (src/index.js)  │    │ (src/server.js) │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                         │
                                                         ▼
                                               ┌─────────────────┐
                                               │  Frontend       │
                                               │  (React + WS)   │
                                               └─────────────────┘

• 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

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

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

• 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

• 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

Most stable and feature-complete option

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

npm run build

# Start canvas server (serves frontend + API)
npm run canvas

# Start both canvas server and Vite dev server
npm run dev

Open your browser and navigate to:

http://localhost:3000

# Currently debugging tool registration - feedback welcome!
npm install -g mcp-excalidraw-server
npx mcp-excalidraw-server

# Canvas sync improvements in progress
docker run -p 3000:3000 mcp-excalidraw-server

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

The MCP server provides these tools for creating visual diagrams:

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

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

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

{
  "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
    }
  ]
}

For the local development version (most stable), add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"]
    }
  }
}

Important: Replace /absolute/path/to/mcp_excalidraw with the actual absolute path to your cloned repository. Note that the path now points to dist/index.js (the compiled TypeScript output).

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Currently debugging tool registration - let us know if you encounter issues!

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-excalidraw-server"]
    }
  }
}

Canvas sync improvements in progress.

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"]
    }
  }
}

For VS Code MCP extension, add to your settings:

{
  "mcp": {
    "servers": {
      "excalidraw": {
        "command": "node",
        "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"]
      }
    }
  }
}

The canvas server provides these REST endpoints:

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

• batch_create_elements - Create complex diagrams in one call

• 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

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

• 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

• 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

• 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

• 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

• Symptoms: MCP tools not registering properly
• Temporary Solution: Use local development setup
• Status: Actively debugging - updates coming soon

• Symptoms: Elements may not sync to canvas immediately
• Temporary Solution: Use local development setup
• Status: Improving synchronization reliability

• Ensure npm run build completed successfully
• Check that dist/index.html exists
• Verify canvas server is running on port 3000

• Confirm MCP server is running (npm start)
• Check ENABLE_CANVAS_SYNC=true in environment
• Verify canvas server is accessible at EXPRESS_SERVER_URL

• Check browser console for WebSocket errors
• Ensure no firewall blocking WebSocket connections
• Try refreshing the browser page

• Delete node_modules and run npm install
• Check Node.js version (requires 16+)
• Ensure all dependencies are installed
• Run npm run type-check to identify TypeScript issues
• Verify dist/ directory is created after npm run build:server

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

• ✅ TypeScript Migration: Complete type safety for enhanced development experience
• NPM Package: Resolving MCP tool registration issues
• Docker Deployment: Improving canvas synchronization
• Enhanced Features: Additional MCP tools and capabilities
• Performance Optimization: Real-time sync improvements
• Advanced TypeScript Features: Stricter type checking and advanced type utilities

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

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

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