Draw.io MCP Server

A Model Context Protocol (MCP) server that provides programmatic tools for creating and managing draw.io diagrams using mxgraph. Generate architecture diagrams, flowcharts, and other visualizations through a clean API that works with Claude Desktop and other MCP-compatible clients.

Overview

This server enables you to build diagrams incrementally by providing stateless tools that operate on .drawio.svg files. Each operation specifies the target file, making it compatible with VSCode's draw.io extension while maintaining a clean separation between diagram state and server operations.

Key Features

• Stateless API: Each tool call specifies the target file path
• VSCode Compatible: Generates .drawio.svg files that work seamlessly with VSCode draw.io extension
• Rich Node Types: Support for rectangles, ellipses, cylinders, clouds, actors, and more
• Connection Management: Create labeled connections with various styling options
• Batch Operations: Create, update, and link multiple nodes in a single MCP call for efficient diagram building
• Flexible Positioning: Precise control over node placement and sizing
• MCP Integration: Works with Claude Desktop and other MCP-compatible applications
• TypeScript: Full type safety and IntelliSense support

Demo

Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn

Configuration

MCP Client Setup

Add this configuration to your MCP client (e.g., Claude Desktop, Cursor):

{
  "mcpServers": {
    "drawio-diagrams": {
      "command": "npx",
      "args": ["drawio-mcp"]
    }
  }
}

File Paths

The server supports both absolute and relative file paths:

• Absolute: /Users/username/project/diagrams/architecture.drawio.svg
• Relative: ./diagrams/architecture.drawio.svg (when cwd is configured)

All diagram files should use the .drawio.svg extension for proper VSCode integration.

Tools Reference

Batch Operations

All primary tools support batch operations, allowing you to perform multiple actions in a single MCP call for improved efficiency:

• add_nodes: Create multiple nodes simultaneously
• edit_nodes: Update multiple nodes/edges simultaneously
• link_nodes: Create multiple connections simultaneously
• remove_nodes: Remove multiple nodes simultaneously

This approach reduces network overhead and provides atomic operations - either all changes succeed or none are applied.

---

new_diagram

Create a new empty diagram file.

Parameters:

• file_path (string, required): Path for the new diagram file

Example:

{
  "file_path": "./diagrams/system-architecture.drawio.svg"
}

add_nodes

Add one or more nodes to an existing diagram in a single operation. Optionally run an automatic layout after insertion.

Parameters:

• file_path (string, required): Path to the diagram file
• layout (object, optional): Automatic layout configuration
  • algorithm (string, required if layout is provided): One of hierarchical, circle, organic, compact-tree, radial-tree, partition, stack
  • options (object, optional): Algorithm-specific options
    • For hierarchical only: direction ∈ "top-down" | "left-right" (default: "top-down")
• nodes (array, required): Array of node objects to add, each containing:
  • id (string, required): Unique identifier for the node
  • title (string, required): Display label (supports newlines with \n)
  • x (number, required): X coordinate position
  • y (number, required): Y coordinate position
  • kind (string, required): Node shape type
  • parent (string, optional): Parent node ID (default: "root")
  • width (number, optional): Custom width
  • height (number, optional): Custom height
  • corner_radius (integer, optional): Corner radius in pixels (≥ 1). Only applies to RoundedRectangle. Default is 12 when kind is RoundedRectangle and corner_radius is omitted. The effective visual radius is capped by draw.io/mxGraph to at most half of the shorter side of the node.

Available Node Types:

• Rectangle: Standard rectangular node
• Ellipse: Oval-shaped node
• Cylinder: Database/storage representation
• Cloud: Cloud service representation
• Square: Square with fixed aspect ratio
• Circle: Circular node
• Step: Process step shape
• Actor: UML actor (stick figure)
• Text: Text-only node
• RoundedRectangle: Rectangle with rounded corners (supports corner_radius in pixels)

Example (Single Node):

{
  "file_path": "./diagrams/system-architecture.drawio.svg",
  "nodes": [
    {
      "id": "user-service",
      "title": "User Service\nAPI Layer",
      "kind": "Rectangle",
      "x": 100,
      "y": 150,
      "width": 120,
      "height": 80
    }
  ]
}

Example (Multiple Nodes):

{
  "file_path": "./diagrams/system-architecture.drawio.svg",
  "nodes": [
    {
      "id": "user-service",
      "title": "User Service",
      "kind": "Rectangle",
      "x": 100,
      "y": 150
    },
    {
      "id": "database",
      "title": "Primary DB",
      "kind": "Cylinder", 
      "x": 300,
      "y": 150
    },
    {
      "id": "cache",
      "title": "Redis Cache",
      "kind": "Cylinder",
      "x": 200,
      "y": 300
    }
  ]
}

Example (With Layout):

{
  "file_path": "./diagrams/system-architecture.drawio.svg",
  "layout": {
    "algorithm": "hierarchical",
    "options": { "direction": "left-right" }
  },
  "nodes": [
    { "id": "api", "title": "API", "kind": "Rectangle", "x": 40, "y": 40 },
    { "id": "service", "title": "Service", "kind": "Rectangle", "x": 200, "y": 40 },
    { "id": "db", "title": "DB", "kind": "Cylinder", "x": 360, "y": 40 }
  ]
}

Note: The layout runs once after all insertions and considers existing edges in the diagram file. For best results when edges are created or modified later, a dedicated layout_diagram tool is recommended (to be added).

link_nodes

Create one or more connections between existing nodes in a single operation.

Parameters:

• file_path (string, required): Path to the diagram file
• edges (array, required): Array of edge objects to create, each containing:
  • from (string, required): Source node ID
  • to (string, required): Target node ID
  • title (string, optional): Connection label
  • dashed (boolean, optional): Whether to use dashed line style
  • reverse (boolean, optional): Whether to reverse arrow direction
  • undirected (boolean, optional): Create an undirected edge (no arrows). Overrides reverse.

Example (Single Connection):

{
  "file_path": "./diagrams/system-architecture.drawio.svg",
  "edges": [
    {
      "from": "user-service",
      "to": "database",
      "title": "queries",
      "dashed": true
    }
  ]
}

Example (Multiple Connections):

{
  "file_path": "./diagrams/system-architecture.drawio.svg",
  "edges": [
    {
      "from": "user-service",
      "to": "database",
      "title": "queries"
    },
    {
      "from": "user-service", 
      "to": "cache",
      "title": "cache lookup",
      "dashed": true
    },
    {
      "from": "database",
      "to": "cache", 
      "title": "invalidate",
      "reverse": true
    }
  ]
}

Example (Undirected Connection):

{
  "file_path": "./diagrams/system-architecture.drawio.svg",
  "edges": [
    {
      "from": "service-a",
      "to": "service-b",
      "title": "peering",
      "undirected": true
    }
  ]
}

Notes on undirected behavior:

• When undirected is true, the edge is rendered without arrowheads (no arrow at either end). The reverse parameter is ignored; dashed is still respected.
• Undirected edges use a canonical ID format of ${min(from,to)}-2-${max(from,to)} when a new edge is created.
• If an edge between the two nodes already exists (in either direction or with the canonical ID), calling link_nodes again will update that existing edge’s label and style rather than creating a duplicate. The existing edge ID is preserved (no renaming).

edit_nodes

Modify properties of one or more existing nodes or edges in a single operation.

Parameters:

• file_path (string, required): Path to the diagram file
• nodes (array, required): Array of node/edge objects to update, each containing:
  • id (string, required): Node or edge ID to update
  • title (string, optional): New display label
  • kind (string, optional): New shape type (nodes only)
  • x (number, optional): New X coordinate (nodes only)
  • y (number, optional): New Y coordinate (nodes only)
  • width (number, optional): New width (nodes only)
  • height (number, optional): New height (nodes only)
  • corner_radius (integer, optional): Corner radius in pixels (≥ 1). Applies when the node is RoundedRectangle. If switching kind to RoundedRectangle and omitted, default 12 is applied. Ignored for other kinds.

Example (Single Node):

{
  "file_path": "./diagrams/system-architecture.drawio.svg",
  "nodes": [
    {
      "id": "user-service",
      "title": "Updated User Service",
      "x": 200,
      "y": 100
    }
  ]
}

Example (Multiple Nodes):

{
  "file_path": "./diagrams/system-architecture.drawio.svg",
  "nodes": [
    {
      "id": "user-service",
      "title": "Auth Service",
      "kind": "Rectangle",
      "x": 200,
      "y": 100
    },
    {
      "id": "database",
      "title": "Updated Database",
      "x": 400,
      "y": 200
    },
    {
      "id": "connection-1",
      "title": "secure connection"
    }
  ]
}

remove_nodes

Remove one or more nodes from a diagram.

Parameters:

• file_path (string, required): Path to the diagram file
• ids (array, required): Array of node IDs to remove

Example:

{
  "file_path": "./diagrams/system-architecture.drawio.svg",
  "ids": ["old-service", "deprecated-db"]
}

get_diagram_info

Retrieve information about a diagram including nodes and connections.

Parameters:

• file_path (string, required): Path to the diagram file

Example:

{
  "file_path": "./diagrams/system-architecture.drawio.svg"
}

Output Format

Diagrams are saved as .drawio.svg files with embedded metadata:

• SVG Format: Clean vector graphics suitable for web and print
• Draw.io Metadata: Full diagram data embedded in SVG for editing
• VSCode Compatible: Open directly in VSCode with draw.io extension
• Self-contained: No external dependencies or additional files needed

Development

Project Structure

src/
├── Graph.ts              # Core graph data structure
├── GraphFileManager.ts   # File I/O operations  
├── Logger.ts            # Logging utilities
├── index.ts             # MCP server entry point
├── mcp/                 # MCP tool implementations
│   ├── McpServer.ts     # Server framework
│   ├── NewDiagramTool.ts
│   ├── AddNodeTool.ts   # Supports batch operations (add_nodes)
│   ├── LinkNodesTools.ts # Supports batch operations (link_nodes)
│   ├── EditNodeTool.ts  # Supports batch operations (edit_nodes)
│   ├── RemoveNodesTool.ts # Supports batch operations (remove_nodes)
│   └── GetDiagramInfoTool.ts
└── mxgraph/             # mxgraph integration
    ├── index.ts
    └── jsdom.ts

Building From Source

# Install dependencies
npm install

# Run TypeScript compilation
npm run build

# Start development server
npm start

# Run linting
npm run lint

Support

• Create an issue on GitHub for bugs and feature requests
• Check existing issues before creating new ones
• Provide detailed reproduction steps for bug reports