Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/fromsko/excalidraw-mcp-server

npx -y @fromsko/excalidraw-mcp-server
https://github.com/fromsko/excalidraw-mcp-server

Last synced: 10 months ago
JSON representation

npx -y @fromsko/excalidraw-mcp-server

Awesome Lists containing this project

README 

          
# MCP Excalidraw Server: Advanced Live Visual Diagramming with AI Integration



> **📦 This is a fork and npm package version maintained by [@fromsko](https://github.com/fromsko)**  

> **🙏 Original project by [@yctimlin](https://github.com/yctimlin/mcp_excalidraw)**  

> **📋 Package name: `@fromsko/excalidraw-mcp-server`**



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**



| Version               | Status                       | Recommended For     |

| --------------------- | ---------------------------- | ------------------- |

| **Local Development** | ✅ **FULLY TESTED**          | **🎯 RECOMMENDED**  |

| **NPM Published**     | 🔧 **DEBUGGING IN PROGRESS** | Development testing |

| **Docker Version**    | 🔧 **UNDER DEVELOPMENT**     | Future deployment   |



### **Current Recommendation: Local Development**



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.



### **Development Notes**



- **NPM Package**: Currently debugging MCP tool registration issues

- **Docker Version**: Improving canvas synchronization reliability

- **Local Version**: ✅ All features fully functional



## 🚀 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!**



[![MCP Excalidraw Demo](https://img.youtube.com/vi/RRN7AF7QIew/maxresdefault.jpg)](https://youtu.be/RRN7AF7QIew)



_Watch how AI agents create and manipulate diagrams in real-time on the live canvas_



## 🏛️ Architecture Overview



```

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐

│   AI Agent      │───▶│   MCP Server     │───▶│  Canvas Server  │

│   (Claude)      │    │  (src/index.js) │    │ (src/server.js) │

└─────────────────┘    └──────────────────┘    └─────────────────┘

                                                         │

                                                         ▼

                                               ┌─────────────────┐

                                               │  Frontend       │

                                               │  (React + WS)   │

                                               └─────────────────┘

```



## 🌟 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



### **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



### **✅ Recommended: Local Development Setup**



> **Most stable and feature-complete option**



#### **1. Clone the Repository**



```bash

git clone https://github.com/fromsko/excalidraw-mcp-server.git

cd excalidraw-mcp-server

npm install

```



#### **2. Build the Frontend**



```bash

npm run build

```



#### **3. Start the System**



##### **Option A: Production Mode (Recommended)**



```bash

# Start canvas server (serves frontend + API)

npm run canvas

```



##### **Option B: Development Mode**



```bash

# Start both canvas server and Vite dev server

npm run dev

```



#### **4. Access the Canvas**



Open your browser and navigate to:



```

http://localhost:3000

```



### **🔧 Alternative Installation Methods (In Development)**



#### **NPM Package (@fromsko/excalidraw-mcp-server)**



```bash

# Install globally

npm install -g @fromsko/excalidraw-mcp-server



# Or run directly

npx @fromsko/excalidraw-mcp-server

```



#### **Docker Version (Coming Soon)**



```bash

# Canvas sync improvements in progress

docker run -p 3000:3000 mcp-excalidraw-server

```



## 🔧 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**



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**



```javascript

// Create a rectangle

{

  "type": "rectangle",

  "x": 100,

  "y": 100,

  "width": 200,

  "height": 100,

  "backgroundColor": "#e3f2fd",

  "strokeColor": "#1976d2",

  "strokeWidth": 2

}

```



#### **Create Text Elements**



```javascript

{

  "type": "text",

  "x": 150,

  "y": 125,

  "text": "Process Step",

  "fontSize": 16,

  "strokeColor": "#333333"

}

```



#### **Create Arrows & Lines**



```javascript

{

  "type": "arrow",

  "x": 300,

  "y": 130,

  "width": 100,

  "height": 0,

  "strokeColor": "#666666",

  "strokeWidth": 2

}

```



#### **Batch Creation for Complex Diagrams**



```javascript

{

  "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

    }

  ]

}

```



## 🔌 Integration with Claude Desktop



### **✅ Recommended: Using Local Installation**



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



```json

{

	"mcpServers": {

		"excalidraw": {

			"command": "node",

			"args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"]

		}

	}

}

```



**Important**: Replace `/absolute/path/to/excalidraw-mcp-server` with the actual absolute path to your cloned repository. Note that the path now points to `dist/index.js` (the compiled TypeScript output).



### **🔧 Alternative Configurations (Beta)**



#### **NPM Package (@fromsko/excalidraw-mcp-server)**



```json

{

	"mcpServers": {

		"excalidraw": {

			"command": "npx",

			"args": ["-y", "@fromsko/excalidraw-mcp-server"]

		}

	}

}

```



#### **Docker Version (Coming Soon)**



```json

{

	"mcpServers": {

		"excalidraw": {

			"command": "docker",

			"args": ["run", "-i", "--rm", "mcp-excalidraw-server"]

		}

	}

}

```



_Canvas sync improvements in progress._



## 🔧 Integration with Other Tools



### **Cursor IDE**



Add to your `.cursor/mcp.json`:



```json

{

	"mcpServers": {

		"excalidraw": {

			"command": "node",

			"args": ["/absolute/path/to/excalidraw-mcp-server/dist/index.js"]

		}

	}

}

```



### **VS Code MCP Extension**



For VS Code MCP extension, add to your settings:



```json

{

	"mcp": {

		"servers": {

			"excalidraw": {

				"command": "node",

				"args": ["/absolute/path/to/excalidraw-mcp-server/dist/index.js"]

			}

		}

	}

}

```



## 🛠️ 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 |

| `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



### **NPM Package Issues**



- **Symptoms**: MCP tools not registering properly

- **Temporary Solution**: Use local development setup

- **Status**: Actively debugging - updates coming soon



### **Docker Version Notes**



- **Symptoms**: Elements may not sync to canvas immediately

- **Temporary Solution**: Use local development setup

- **Status**: Improving synchronization reliability



### **Canvas Not Loading**



- Ensure `npm run build` completed successfully

- Check that `dist/index.html` exists

- Verify canvas server is running on port 3000



### **Elements Not Syncing**



- Confirm MCP server is running (`npm start`)

- Check `ENABLE_CANVAS_SYNC=true` in environment

- Verify canvas server is accessible at `EXPRESS_SERVER_URL`



### **WebSocket Connection Issues**



- Check browser console for WebSocket errors

- Ensure no firewall blocking WebSocket connections

- Try refreshing the browser page



### **Build Errors**



- 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`



## 📋 Project Structure



```

excalidraw-mcp-server/

├── 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

- **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



## 🤝 Contributing



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



## 🙏 Acknowledgments



- **Original Author**: [@yctimlin](https://github.com/yctimlin) - Thank you for creating this amazing project!

- **Original Repository**: [mcp_excalidraw](https://github.com/yctimlin/mcp_excalidraw)

- **Excalidraw Team**: For the fantastic drawing library

- **MCP Community**: For the Model Context Protocol



## 📜 Contributors



- **[@yctimlin](https://github.com/yctimlin)** - Original creator and developer

- **[@fromsko](https://github.com/fromsko)** - Package maintainer and fork contributor



## 📝 License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



**Note**: This is a fork of the original project by yctimlin. All credit for the original implementation goes to the original author.



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](LICENSE) file for details.



## 🙏 Acknowledgments



- **Excalidraw Team** - For the amazing drawing library

- **MCP Community** - For the Model Context Protocol specification