drawio-mcp-server

Implements the Model Context Protocol (MCP) specification to expose Draw.io as a callable tool interface for LLM clients like Claude Desktop and oterm. The server receives structured tool calls from MCP clients, translates them into Draw.io operations via a WebSocket-connected browser extension, and returns structured responses back through the MCP protocol. Uses the @modelcontextprotocol/sdk (v1.10.1) for protocol implementation and event-driven message routing through Node.js EventEmitter.

Operates a uWebSockets.js server on port 3000 that maintains persistent WebSocket connections with the Draw.io MCP Browser Extension, enabling real-time bidirectional message exchange. Commands from MCP clients are queued and sent to the extension, which executes them in the Draw.io DOM context and returns results asynchronously. The event bus (Node.js EventEmitter) decouples incoming MCP requests from outgoing WebSocket messages, allowing multiple concurrent diagram operations.

Manages WebSocket connection lifecycle with the Draw.io MCP Browser Extension, including initial handshake, connection validation, and graceful disconnection handling. When the extension connects, the server validates the connection, registers event listeners for incoming messages, and begins routing MCP requests to the extension. On disconnection, the server cleans up event listeners and queues pending operations for retry or failure notification to MCP clients.

Maintains a registry of available tools (add-rectangle, update-cell-properties, delete-cell, etc.) with their schemas, descriptions, and input/output specifications. When an MCP client connects, the server exposes this tool registry through the MCP protocol, allowing clients to discover available operations and their parameters. Tools are dynamically loaded from the tool system and registered with their zod schemas, enabling MCP clients to understand tool capabilities without hardcoding.

Provides tools to query the current state of a Draw.io diagram without modifying it: get-selected-cell retrieves properties of the currently selected element, get-shape-categories lists available shape libraries, get-shapes-in-category enumerates shapes within a category, and get-shape-by-name finds specific shapes by name. These tools execute read-only queries through the WebSocket connection to the browser extension, which accesses the Draw.io DOM to extract metadata and return structured JSON responses.

Provides tools to create diagram elements (rectangles, circles, diamonds, text, connectors) with validated properties using zod schema validation. Tools like add-rectangle, add-circle, add-diamond, add-text, and add-connector accept structured input parameters (position, size, style, label, connections) that are validated against predefined schemas before being sent to the Draw.io extension. The extension executes the creation in the Draw.io DOM and returns the created element's ID and properties.

Provides tools to modify existing diagram elements after creation: update-cell-properties changes properties of a selected or specified element (label, style, position, size), delete-cell removes elements from the diagram, and style-cell applies predefined or custom styling. Modifications are sent through the WebSocket connection to the browser extension, which updates the Draw.io DOM and returns confirmation with updated element state. Uses event-driven message routing to queue modifications and handle asynchronous responses.

Provides the add-connector tool to create connections between diagram elements with validated source and target element IDs. The tool accepts source element ID, target element ID, and optional label/style properties, validates the IDs exist, and sends the connector creation request through WebSocket to the Draw.io extension. The extension creates the connector in the DOM and returns the connector's ID and properties, enabling programmatic relationship mapping in diagrams.

Implements a Node.js EventEmitter-based message bus with two primary event streams: bus_request_stream for commands flowing from MCP clients to Draw.io, and bus_reply_stream for results flowing back from the browser extension to MCP clients. This decouples the MCP protocol layer from WebSocket communication, allowing multiple concurrent tool calls to be queued and processed asynchronously without blocking. Requests are assigned unique IDs (via nanoid v5.1.5) to correlate responses with requests.

Integrates pino v9.6.0 logging library to provide structured JSON logging with request ID correlation. Each MCP request and WebSocket message is logged with its unique ID, operation type, timestamp, and result status. Logs include both request entry points and response completion, enabling end-to-end tracing of diagram operations through the system. Logging is configurable and outputs to stdout/stderr with optional file rotation.

Defines all MCP tool inputs using zod v3.24.3 schemas, providing runtime validation and type safety for tool parameters. Each tool (add-rectangle, update-cell-properties, etc.) has a corresponding zod schema that validates input types, required fields, and value constraints (e.g., numeric ranges for coordinates). Invalid inputs are rejected with detailed error messages before being sent to the Draw.io extension, ensuring only valid operations reach the browser.

Uses nanoid v5.1.5 to generate unique, URL-safe IDs for diagram elements created through the MCP server. Each new element (rectangle, circle, connector, etc.) is assigned a unique ID that persists for the element's lifetime in the diagram. IDs are also used to correlate asynchronous MCP requests with WebSocket responses, enabling request-response matching in the event bus.