excalidraw-mcp-server

jsuryahyd/excalidraw-mcp-server

3.2

If you are the rightful owner of excalidraw-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Excalidraw MCP Server is a robust Model Context Protocol (MCP) server designed to enable AI agents to create high-quality Excalidraw diagrams programmatically.

Tools
3
Resources
0
Prompts
0

Excalidraw MCP Server

A robust Model Context Protocol (MCP) server that enables AI agents to create high-quality Excalidraw diagrams programmatically.

Features

Phase 1 (Current) ✅

  • ✅ Core HTTP & WebSocket server
  • ✅ MCP SDK integration with stdio transport
  • ✅ Basic element creation tools (rectangle, text, ellipse, diamond, arrow, line)
  • ✅ In-memory state management with versioning
  • ✅ Optimistic locking for concurrent modifications
  • ✅ Zod schema validation for all inputs
  • ✅ Real-time WebSocket broadcasting
  • ✅ Basic integration tests

Installation

Prerequisites

  • Node.js >= 18.0.0
  • npm >= 9.0.0

Install Dependencies

npm install

Build

npm run build

Usage

Running in HTTP/WebSocket Mode

Start the server for web-based access:

npm start

Or in development mode with auto-reload:

npm run dev

The server will start on http://localhost:3000 by default.

Running in MCP Mode

⚠️ Note: MCP stdio mode is currently under development due to MCP SDK API changes. The HTTP/WebSocket mode is fully functional.

For use with MCP clients (Claude Desktop, Cursor, etc.):

npm run dev -- --mcp

This will start the server in stdio mode for MCP protocol communication (currently being debugged).

API Endpoints

HTTP Endpoints

Health Check
GET /health

Returns server status and element count.

Get All Elements
GET /api/elements

Returns all diagram elements.

Get Single Element
GET /api/elements/:id

Returns a specific element by ID.

Clear Canvas
DELETE /api/elements

Removes all elements from the canvas.

WebSocket Events

The server broadcasts the following events to all connected clients:

  • sync: Full state synchronization (sent on connection)
  • element_created: New element added
  • element_updated: Element modified
  • element_deleted: Element removed

MCP Tools

createRectangle

Create a rectangle element on the canvas.

Parameters:

  • id (string, required): Unique identifier
  • x (number, required): X coordinate
  • y (number, required): Y coordinate
  • width (number, required): Width
  • height (number, required): Height
  • strokeColor (string, optional): Stroke color (hex)
  • backgroundColor (string, optional): Background color (hex)
  • fillStyle (string, optional): Fill style (hachure, cross-hatch, solid)
  • strokeWidth (number, optional): Stroke width
  • strokeStyle (string, optional): Stroke style (solid, dashed, dotted)

createText

Create a text element on the canvas.

Parameters:

  • id (string, required): Unique identifier
  • x (number, required): X coordinate
  • y (number, required): Y coordinate
  • text (string, required): Text content
  • fontSize (number, optional): Font size
  • fontFamily (number, optional): Font family (1-4)
  • textAlign (string, optional): Text alignment (left, center, right)

getAllElements

Get all elements from the canvas.

Parameters: None

Development

Run Tests

npm test

Run Tests with Coverage

npm run test:coverage

Lint Code

npm run lint

Format Code

npm run format

Architecture

Core Components

  • DiagramStore: In-memory storage with versioning and optimistic locking
  • MCP Server: Handles MCP protocol communication via stdio
  • HTTP/WebSocket Server: Provides REST API and real-time updates
  • Zod Schemas: Input validation for all operations

Element Versioning

All elements include a version field that increments with each update. This enables optimistic locking to prevent concurrent modification conflicts (FR-006, FR-007, FR-008).

Batch Operations

Multiple elements can be created in a single operation. If any element in the batch is invalid, the entire batch is rejected (FR-005a).

Configuration

Environment variables (optional):

  • PORT: Server port (default: 3000)
  • HOST: Server host (default: localhost)

Testing

The project includes integration tests for:

  • Element creation and storage
  • Version management and optimistic locking
  • Batch operations with rollback
  • Error handling and validation

License

ISC

Contributing

This project follows the specification in specs/001-excalidraw-mcp-server/spec.md.

Roadmap

See specs/001-excalidraw-mcp-server/plan.md for the complete implementation plan.

Upcoming Phases

  • Phase 2: Real-time synchronization enhancements & frontend
  • Phase 3: Diagram persistence with SQLite
  • Phase 4: Advanced features (intelligent positioning, user preferences)
  • Phase 5: Deployment, testing & documentation