{"id":30691310,"url":"https://github.com/fromsko/excalidraw-mcp-server","last_synced_at":"2025-09-02T03:48:14.082Z","repository":{"id":311574283,"uuid":"1044084960","full_name":"Fromsko/excalidraw-mcp-server","owner":"Fromsko","description":"npx -y @fromsko/excalidraw-mcp-server","archived":false,"fork":false,"pushed_at":"2025-08-25T06:55:42.000Z","size":80,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-25T10:52:48.418Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Fromsko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-25T06:55:36.000Z","updated_at":"2025-08-25T06:56:39.000Z","dependencies_parsed_at":"2025-08-25T10:52:49.745Z","dependency_job_id":"931806fe-9c8f-41c0-ba6e-4795915f7f46","html_url":"https://github.com/Fromsko/excalidraw-mcp-server","commit_stats":null,"previous_names":["fromsko/excalidraw-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Fromsko/excalidraw-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fromsko%2Fexcalidraw-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fromsko%2Fexcalidraw-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fromsko%2Fexcalidraw-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fromsko%2Fexcalidraw-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fromsko","download_url":"https://codeload.github.com/Fromsko/excalidraw-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fromsko%2Fexcalidraw-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273227500,"owners_count":25067686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-02T03:48:13.192Z","updated_at":"2025-09-02T03:48:14.069Z","avatar_url":"https://github.com/Fromsko.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Excalidraw Server: Advanced Live Visual Diagramming with AI Integration\n\n\u003e **📦 This is a fork and npm package version maintained by [@fromsko](https://github.com/fromsko)**  \n\u003e **🙏 Original project by [@yctimlin](https://github.com/yctimlin/mcp_excalidraw)**  \n\u003e **📋 Package name: `@fromsko/excalidraw-mcp-server`**\n\nA 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.\n\n## 🚦 Current Status \u0026 Version Information\n\n\u003e **📋 Choose Your Installation Method**\n\n| Version               | Status                       | Recommended For     |\n| --------------------- | ---------------------------- | ------------------- |\n| **Local Development** | ✅ **FULLY TESTED**          | **🎯 RECOMMENDED**  |\n| **NPM Published**     | 🔧 **DEBUGGING IN PROGRESS** | Development testing |\n| **Docker Version**    | 🔧 **UNDER DEVELOPMENT**     | Future deployment   |\n\n### **Current Recommendation: Local Development**\n\nFor the most stable experience, we recommend using the local development setup. We're actively working on improving the NPM package and Docker deployment options.\n\n### **Development Notes**\n\n- **NPM Package**: Currently debugging MCP tool registration issues\n- **Docker Version**: Improving canvas synchronization reliability\n- **Local Version**: ✅ All features fully functional\n\n## 🚀 What This System Does\n\n- **🎨 Live Canvas**: Real-time Excalidraw canvas accessible via web browser\n- **🤖 AI Integration**: MCP server allows AI agents (like Claude) to create visual diagrams\n- **⚡ Real-time Sync**: Elements created via MCP API appear instantly on the canvas\n- **🔄 WebSocket Updates**: Live synchronization across multiple connected clients\n- **🏗️ Production Ready**: Clean, minimal UI suitable for end users\n\n## 🎥 Demo Video\n\n\u003e **See MCP Excalidraw in Action!**\n\n[![MCP Excalidraw Demo](https://img.youtube.com/vi/RRN7AF7QIew/maxresdefault.jpg)](https://youtu.be/RRN7AF7QIew)\n\n_Watch how AI agents create and manipulate diagrams in real-time on the live canvas_\n\n## 🏛️ Architecture Overview\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   AI Agent      │───▶│   MCP Server     │───▶│  Canvas Server  │\n│   (Claude)      │    │  (src/index.js) │    │ (src/server.js) │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n                                                         │\n                                                         ▼\n                                               ┌─────────────────┐\n                                               │  Frontend       │\n                                               │  (React + WS)   │\n                                               └─────────────────┘\n```\n\n## 🌟 Key Features\n\n### **Modern TypeScript Architecture**\n\n- **Full TypeScript Migration**: Complete type safety for backend and frontend\n- **Comprehensive Type Definitions**: Excalidraw elements, API responses, WebSocket messages\n- **Strict Type Checking**: Enhanced development experience and compile-time error detection\n- **Type-Safe React Components**: TSX components with proper props typing\n\n### **Real-time Canvas Integration**\n\n- Elements created via MCP appear instantly on the live canvas\n- WebSocket-based real-time synchronization\n- Multi-client support with live updates\n\n### **Production-Ready Interface**\n\n- Clean, minimal UI with connection status\n- Simple \"Clear Canvas\" functionality\n- No development clutter or debug information\n\n### **Comprehensive MCP API**\n\n- **Element Creation**: rectangles, ellipses, diamonds, arrows, text, lines\n- **Element Management**: update, delete, query with filters\n- **Batch Operations**: create multiple elements in one call\n- **Advanced Features**: grouping, alignment, distribution, locking\n\n### **Robust Architecture**\n\n- TypeScript-based Express.js backend with REST API + WebSocket\n- React frontend with official Excalidraw package and TypeScript\n- Dual-path element loading for reliability\n- Auto-reconnection and error handling\n\n## 📦 Installation \u0026 Setup\n\n### **✅ Recommended: Local Development Setup**\n\n\u003e **Most stable and feature-complete option**\n\n#### **1. Clone the Repository**\n\n```bash\ngit clone https://github.com/fromsko/excalidraw-mcp-server.git\ncd excalidraw-mcp-server\nnpm install\n```\n\n#### **2. Build the Frontend**\n\n```bash\nnpm run build\n```\n\n#### **3. Start the System**\n\n##### **Option A: Production Mode (Recommended)**\n\n```bash\n# Start canvas server (serves frontend + API)\nnpm run canvas\n```\n\n##### **Option B: Development Mode**\n\n```bash\n# Start both canvas server and Vite dev server\nnpm run dev\n```\n\n#### **4. Access the Canvas**\n\nOpen your browser and navigate to:\n\n```\nhttp://localhost:3000\n```\n\n### **🔧 Alternative Installation Methods (In Development)**\n\n#### **NPM Package (@fromsko/excalidraw-mcp-server)**\n\n```bash\n# Install globally\nnpm install -g @fromsko/excalidraw-mcp-server\n\n# Or run directly\nnpx @fromsko/excalidraw-mcp-server\n```\n\n#### **Docker Version (Coming Soon)**\n\n```bash\n# Canvas sync improvements in progress\ndocker run -p 3000:3000 mcp-excalidraw-server\n```\n\n## 🔧 Available Scripts\n\n| Script                   | Description                                      |\n| ------------------------ | ------------------------------------------------ |\n| `npm start`              | Build and start MCP server (`dist/index.js`)     |\n| `npm run canvas`         | Build and start canvas server (`dist/server.js`) |\n| `npm run build`          | Build both frontend and TypeScript backend       |\n| `npm run build:frontend` | Build React frontend only                        |\n| `npm run build:server`   | Compile TypeScript backend to JavaScript         |\n| `npm run dev`            | Start TypeScript watch mode + Vite dev server    |\n| `npm run type-check`     | Run TypeScript type checking without compilation |\n| `npm run production`     | Build + start in production mode                 |\n\n## 🎯 Usage Guide\n\n### **For End Users**\n\n1. Open the canvas at `http://localhost:3000`\n2. Check connection status (should show \"Connected\")\n3. AI agents can now create diagrams that appear in real-time\n4. Use \"Clear Canvas\" to remove all elements\n\n### **For AI Agents (via MCP)**\n\nThe MCP server provides these tools for creating visual diagrams:\n\n#### **Basic Element Creation**\n\n```javascript\n// Create a rectangle\n{\n  \"type\": \"rectangle\",\n  \"x\": 100,\n  \"y\": 100,\n  \"width\": 200,\n  \"height\": 100,\n  \"backgroundColor\": \"#e3f2fd\",\n  \"strokeColor\": \"#1976d2\",\n  \"strokeWidth\": 2\n}\n```\n\n#### **Create Text Elements**\n\n```javascript\n{\n  \"type\": \"text\",\n  \"x\": 150,\n  \"y\": 125,\n  \"text\": \"Process Step\",\n  \"fontSize\": 16,\n  \"strokeColor\": \"#333333\"\n}\n```\n\n#### **Create Arrows \u0026 Lines**\n\n```javascript\n{\n  \"type\": \"arrow\",\n  \"x\": 300,\n  \"y\": 130,\n  \"width\": 100,\n  \"height\": 0,\n  \"strokeColor\": \"#666666\",\n  \"strokeWidth\": 2\n}\n```\n\n#### **Batch Creation for Complex Diagrams**\n\n```javascript\n{\n  \"elements\": [\n    {\n      \"type\": \"rectangle\",\n      \"x\": 100,\n      \"y\": 100,\n      \"width\": 120,\n      \"height\": 60,\n      \"backgroundColor\": \"#fff3e0\",\n      \"strokeColor\": \"#ff9800\"\n    },\n    {\n      \"type\": \"text\",\n      \"x\": 130,\n      \"y\": 125,\n      \"text\": \"Start\",\n      \"fontSize\": 16\n    }\n  ]\n}\n```\n\n## 🔌 Integration with Claude Desktop\n\n### **✅ Recommended: Using Local Installation**\n\nFor the **local development version** (most stable), add this configuration to your `claude_desktop_config.json`:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"excalidraw\": {\n\t\t\t\"command\": \"node\",\n\t\t\t\"args\": [\"/absolute/path/to/mcp_excalidraw/dist/index.js\"]\n\t\t}\n\t}\n}\n```\n\n**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).\n\n### **🔧 Alternative Configurations (Beta)**\n\n#### **NPM Package (@fromsko/excalidraw-mcp-server)**\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"excalidraw\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"@fromsko/excalidraw-mcp-server\"]\n\t\t}\n\t}\n}\n```\n\n#### **Docker Version (Coming Soon)**\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"excalidraw\": {\n\t\t\t\"command\": \"docker\",\n\t\t\t\"args\": [\"run\", \"-i\", \"--rm\", \"mcp-excalidraw-server\"]\n\t\t}\n\t}\n}\n```\n\n_Canvas sync improvements in progress._\n\n## 🔧 Integration with Other Tools\n\n### **Cursor IDE**\n\nAdd to your `.cursor/mcp.json`:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"excalidraw\": {\n\t\t\t\"command\": \"node\",\n\t\t\t\"args\": [\"/absolute/path/to/excalidraw-mcp-server/dist/index.js\"]\n\t\t}\n\t}\n}\n```\n\n### **VS Code MCP Extension**\n\nFor VS Code MCP extension, add to your settings:\n\n```json\n{\n\t\"mcp\": {\n\t\t\"servers\": {\n\t\t\t\"excalidraw\": {\n\t\t\t\t\"command\": \"node\",\n\t\t\t\t\"args\": [\"/absolute/path/to/excalidraw-mcp-server/dist/index.js\"]\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n## 🛠️ Environment Variables\n\n| Variable             | Default                 | Description                           |\n| -------------------- | ----------------------- | ------------------------------------- |\n| `EXPRESS_SERVER_URL` | `http://localhost:3000` | Canvas server URL for MCP sync        |\n| `ENABLE_CANVAS_SYNC` | `true`                  | Enable/disable canvas synchronization |\n| `DEBUG`              | `false`                 | Enable debug logging                  |\n| `PORT`               | `3000`                  | Canvas server port                    |\n| `HOST`               | `localhost`             | Canvas server host                    |\n\n## 📊 API Endpoints\n\nThe canvas server provides these REST endpoints:\n\n| Method   | Endpoint              | Description              |\n| -------- | --------------------- | ------------------------ |\n| `GET`    | `/api/elements`       | Get all elements         |\n| `POST`   | `/api/elements`       | Create new element       |\n| `PUT`    | `/api/elements/:id`   | Update element           |\n| `DELETE` | `/api/elements/:id`   | Delete element           |\n| `POST`   | `/api/elements/batch` | Create multiple elements |\n| `GET`    | `/health`             | Server health check      |\n\n## 🎨 MCP Tools Available\n\n### **Element Management**\n\n- `create_element` - Create any type of Excalidraw element\n- `update_element` - Modify existing elements\n- `delete_element` - Remove elements\n- `query_elements` - Search elements with filters\n\n### **Batch Operations**\n\n- `batch_create_elements` - Create complex diagrams in one call\n\n### **Element Organization**\n\n- `group_elements` - Group multiple elements\n- `ungroup_elements` - Ungroup element groups\n- `align_elements` - Align elements (left, center, right, top, middle, bottom)\n- `distribute_elements` - Distribute elements evenly\n- `lock_elements` / `unlock_elements` - Lock/unlock elements\n\n### **Resource Access**\n\n- `get_resource` - Access scene, library, theme, or elements data\n\n## 🏗️ Development Architecture\n\n### **Frontend** (`frontend/src/`)\n\n- **React + TypeScript**: Modern TSX components with full type safety\n- **Vite Build System**: Fast development and optimized production builds\n- **Official Excalidraw**: `@excalidraw/excalidraw` package with TypeScript types\n- **WebSocket Client**: Type-safe real-time element synchronization\n- **Clean UI**: Production-ready interface with proper TypeScript typing\n\n### **Canvas Server** (`src/server.ts` → `dist/server.js`)\n\n- **TypeScript + Express.js**: Fully typed REST API + static file serving\n- **WebSocket**: Type-safe real-time client communication\n- **Element Storage**: In-memory with comprehensive type definitions\n- **CORS**: Cross-origin support with proper typing\n\n### **MCP Server** (`src/index.ts` → `dist/index.js`)\n\n- **TypeScript MCP Protocol**: Type-safe Model Context Protocol implementation\n- **Canvas Sync**: Strongly typed HTTP requests to canvas server\n- **Element Management**: Full CRUD operations with comprehensive type checking\n- **Batch Support**: Type-safe complex diagram creation\n\n### **Type System** (`src/types.ts`)\n\n- **Excalidraw Element Types**: Complete type definitions for all element types\n- **API Response Types**: Strongly typed REST API interfaces\n- **WebSocket Message Types**: Type-safe real-time communication\n- **Server Element Types**: Enhanced element types with metadata\n\n## 🐛 Troubleshooting\n\n### **NPM Package Issues**\n\n- **Symptoms**: MCP tools not registering properly\n- **Temporary Solution**: Use local development setup\n- **Status**: Actively debugging - updates coming soon\n\n### **Docker Version Notes**\n\n- **Symptoms**: Elements may not sync to canvas immediately\n- **Temporary Solution**: Use local development setup\n- **Status**: Improving synchronization reliability\n\n### **Canvas Not Loading**\n\n- Ensure `npm run build` completed successfully\n- Check that `dist/index.html` exists\n- Verify canvas server is running on port 3000\n\n### **Elements Not Syncing**\n\n- Confirm MCP server is running (`npm start`)\n- Check `ENABLE_CANVAS_SYNC=true` in environment\n- Verify canvas server is accessible at `EXPRESS_SERVER_URL`\n\n### **WebSocket Connection Issues**\n\n- Check browser console for WebSocket errors\n- Ensure no firewall blocking WebSocket connections\n- Try refreshing the browser page\n\n### **Build Errors**\n\n- Delete `node_modules` and run `npm install`\n- Check Node.js version (requires 16+)\n- Ensure all dependencies are installed\n- Run `npm run type-check` to identify TypeScript issues\n- Verify `dist/` directory is created after `npm run build:server`\n\n## 📋 Project Structure\n\n```\nexcalidraw-mcp-server/\n├── frontend/\n│   ├── src/\n│   │   ├── App.tsx          # Main React component (TypeScript)\n│   │   └── main.tsx         # React entry point (TypeScript)\n│   └── index.html           # HTML template\n├── src/ (TypeScript Source)\n│   ├── index.ts            # MCP server (TypeScript)\n│   ├── server.ts           # Canvas server (Express + WebSocket, TypeScript)\n│   ├── types.ts            # Comprehensive type definitions\n│   └── utils/\n│       └── logger.ts       # Logging utility (TypeScript)\n├── dist/ (Compiled Output)\n│   ├── index.js            # Compiled MCP server\n│   ├── server.js           # Compiled Canvas server\n│   ├── types.js            # Compiled type definitions\n│   ├── utils/\n│   │   └── logger.js       # Compiled logging utility\n│   └── frontend/           # Built React frontend\n├── tsconfig.json          # TypeScript configuration\n├── vite.config.js         # Vite build configuration\n├── package.json           # Dependencies and scripts\n└── README.md              # This file\n```\n\n## 🔮 Development Roadmap\n\n- ✅ **TypeScript Migration**: Complete type safety for enhanced development experience\n- **NPM Package**: Resolving MCP tool registration issues\n- **Docker Deployment**: Improving canvas synchronization\n- **Enhanced Features**: Additional MCP tools and capabilities\n- **Performance Optimization**: Real-time sync improvements\n- **Advanced TypeScript Features**: Stricter type checking and advanced type utilities\n\n## 🤝 Contributing\n\nWe welcome contributions! If you're experiencing issues with the NPM package or Docker version, please:\n\n## 🙏 Acknowledgments\n\n- **Original Author**: [@yctimlin](https://github.com/yctimlin) - Thank you for creating this amazing project!\n- **Original Repository**: [mcp_excalidraw](https://github.com/yctimlin/mcp_excalidraw)\n- **Excalidraw Team**: For the fantastic drawing library\n- **MCP Community**: For the Model Context Protocol\n\n## 📜 Contributors\n\n- **[@yctimlin](https://github.com/yctimlin)** - Original creator and developer\n- **[@fromsko](https://github.com/fromsko)** - Package maintainer and fork contributor\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n**Note**: This is a fork of the original project by yctimlin. All credit for the original implementation goes to the original author.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **Excalidraw Team** - For the amazing drawing library\n- **MCP Community** - For the Model Context Protocol specification\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffromsko%2Fexcalidraw-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffromsko%2Fexcalidraw-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffromsko%2Fexcalidraw-mcp-server/lists"}