Draw.io MCP Server

A Model Context Protocol (MCP) server for programmatic diagram generation using Draw.io (Diagrams.net). This server generates Draw.io XML directly — no browser extension or Draw.io instance required.

Demo Video

Acknowledgements

This project would not exist in this manner if it weren't for the following repositories and their authors. Thank you!

• Original drawio-mcp-server by Ladislav (lgazo): https://github.com/lgazo/drawio-mcp-server
• Azure icons source (dwarfered): https://github.com/dwarfered/azure-architecture-icons-for-drawio
• VS Code Drawio extension by hediet: https://github.com/hediet/vscode-drawio

Features

• 700+ Azure Architecture Icons — Official Microsoft icons with embedded SVG data, organized into ~20 categories (Compute, Networking, Storage, Databases, AI + ML, Security, and more)
• Basic Shapes — Rectangles, ellipses, diamonds, parallelograms, and other flowchart primitives
• Fuzzy Search — Find shapes by partial name across the entire icon library
• Batch Operations — Create and update multiple cells in a single call for better performance
• Layer Management — Create, list, and organize cells across layers
• Style Presets — Built-in Azure, flowchart, and general color presets
• Multiple Transports — stdio (default) and streamable HTTP
• XML Export — Standard Draw.io XML format compatible with Draw.io desktop and web

For PNG/SVG/PDF conversion, use jgraph's Draw.io skill-cli workflow: https://github.com/jgraph/drawio-mcp/blob/main/skill-cli/README.md.

Documentation

• Transactional mode design: docs/transactional_mode_design.md

Requirements

• Deno v2.3 or higher

Quick Start

From Source

deno run --allow-net --allow-read --allow-env src/index.ts

MCP Client Configuration

Configure your MCP client (Claude Desktop, VS Code, Codex, etc.) to use the server:

{
  "mcpServers": {
    "drawio": {
      "command": "deno",
      "args": ["run", "--allow-net", "--allow-read", "--allow-env", "/path/to/drawio-mcp-server/src/index.ts"]
    }
  }
}

{
  "mcpServers": {
    "drawio": {
      "command": "deno",
      "args": ["run", "--allow-net", "--allow-read", "--allow-env", "/path/to/drawio-mcp-server/src/index.ts"]
    }
  }
}

{
  "drawio": {
    "command": "deno",
    "args": ["run", "--allow-net", "--allow-read", "--allow-env", "/path/to/drawio-mcp-server/src/index.ts"],
    "env": {}
  }
}

[mcp_servers.drawio]
command = "deno"
args = ["run", "--allow-net", "--allow-read", "--allow-env", "/path/to/drawio-mcp-server/src/index.ts"]

[mcp_servers.drawio]
url = "http://localhost:8080/mcp"

{
  "mcpServers": {
    "drawio": {
      "command": "deno",
      "args": ["run", "--allow-net", "--allow-read", "--allow-env", "/path/to/drawio-mcp-server/src/index.ts"]
    }
  }
}

Configuration

Transport Selection

The --transport flag controls which transports to start. Default is stdio.

Environment Variables

Tip: You can create a .env file from .env.example to configure environment variables locally:

cp .env.example .env
# Edit .env and uncomment/set SAVE_DIAGRAMS=true or other variables

The server automatically loads .env files at startup. The .env file is gitignored and won't be committed to the repository.

Development Mode — Auto-save Diagrams

⚠️ WARNING: DEVELOPMENT MODE ONLY — NOT FOR PRODUCTION USE

For local debugging and development, you can enable automatic saving of diagram XML to a local diagrams/ folder. This is useful for inspecting generated diagrams without manually copying XML output.

To enable:

export SAVE_DIAGRAMS=true
deno task start

or

SAVE_DIAGRAMS=true deno task start

Behavior when enabled:

• Every call to export-diagram or finish-diagram automatically saves the XML to ./diagrams/<timestamp>_<tool-name>.drawio
• Timestamp format: YYYYMMDD_HHMMSS (e.g., 20260219_143052_export-diagram.drawio)
• The diagrams/ folder is created automatically if it doesn't exist
• Errors during file saving are logged but do not fail the tool operation

To disable (default):

Simply unset the environment variable or set it to any value other than true or 1:

unset SAVE_DIAGRAMS

or

export SAVE_DIAGRAMS=false

Security note: This feature is disabled by default and should never be enabled in production or containerized deployments. It is intended solely for local development and debugging.

HTTP Transport

The HTTP transport exposes a streamable HTTP endpoint at /mcp (default port 8080).

deno task start:http
# or with a custom port:
deno run --allow-net --allow-read --allow-env src/index.ts --transport http --http-port 4000

MCP client configuration for HTTP:

{
  "mcpServers": {
    "drawio": {
      "command": "deno",
      "args": [
        "run",
        "--allow-net",
        "--allow-read",
        "--allow-env",
        "/path/to/drawio-mcp-server/src/index.ts",
        "--transport",
        "http",
        "--http-port",
        "4000"
      ]
    }
  }
}

Health check: curl http://localhost:8080/health

Docker

The Docker image uses deno compile to produce a self-contained native binary, then runs it on a minimal distroless base image (~20MB) with no shell, no package manager, and a non-root user.

Pulling from Docker Hub

A pre-built image is available on Docker Hub. This is the fastest way to get started — no cloning or building required.

1. Pull the latest image:

docker pull simonkurtzmsft/drawio-mcp-server:latest

2. Start the container:

docker run -d --name drawio-mcp-server -p 8080:8080 simonkurtzmsft/drawio-mcp-server:latest

This starts the server in the background, exposing the HTTP transport on port 8080.

3. Verify the server is running:

curl http://localhost:8080/health

You should receive an OK response, confirming the server is healthy and ready to accept connections.

4. Point your MCP client to the running container. For example, in VS Code (.vscode/mcp.json):

{
  "mcpServers": {
    "drawio": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Or in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "drawio": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

5. To stop and remove the container:

docker stop drawio-mcp-server
docker rm drawio-mcp-server

Building Locally

To build the image from source instead of pulling from Docker Hub:

# Build
docker build -t drawio-mcp-server .

# Run (exposes HTTP on port 8080)
docker run -d --name drawio-mcp-server -p 8080:8080 drawio-mcp-server

Docker Compose

cp .env.example .env   # Configure REGISTRY and IMAGE_VERSION
docker compose up -d

The .env file supports:

• REGISTRY — Docker registry URL (e.g., docker.io/myusername)
• IMAGE_VERSION — Semantic version for image tags (e.g., 1.0.0)

Note: The distroless image has no shell, so in-container health checks (wget, curl) are not available. Use external health checks (e.g., Kubernetes liveness probes, load balancer health checks) to monitor the /health endpoint.

Tools

Performance tip: All cell-manipulation tools accept arrays — pass ALL items in a single call rather than calling a tool repeatedly.

Stateless contract: Diagram tools are stateless per call. Pass the full prior diagram_xml into each diagram-related tool call, and carry forward the returned diagram_xml from the response for the next call.

Shape Discovery

Diagram Modification

Diagram Inspection

Layer Management

Page Management

Group / Container Management

Add Cells Example

Use add-cells with temp_id references to create vertices and edges in a single call:

{
  "cells": [
    {
      "type": "vertex",
      "temp_id": "web",
      "x": 100,
      "y": 100,
      "width": 60,
      "height": 60,
      "text": "Web",
      "style": "aspect=fixed;html=1;image;image=img/lib/azure2/compute/Container_Instances.svg;"
    },
    {
      "type": "vertex",
      "temp_id": "api",
      "x": 220,
      "y": 100,
      "width": 60,
      "height": 60,
      "text": "API",
      "style": "aspect=fixed;html=1;image;image=img/lib/azure2/compute/Container_Instances.svg;"
    },
    { "type": "edge", "source_id": "web", "target_id": "api", "text": "HTTPS" }
  ]
}

Azure Icon Library

The server includes 700+ official Azure architecture icons from dwarfered/azure-architecture-icons-for-drawio, organized into categories:

Icons use embedded base64 SVG data — no external dependencies, works fully offline with correct Azure branding and colors.

The library loads lazily on first access (singleton pattern). Search operations are <5ms after initial load.

Development

Setup

git clone https://github.com/simonkurtz-MSFT/drawio-mcp-server.git
cd drawio-mcp-server

No install step needed — Deno resolves dependencies on first run.

Common Commands

MCP Inspector

Use the MCP Inspector to debug the server:

deno task inspect

After making changes, Restart the Inspector. After changing tool definitions, Clear and List the tools again.

Related Approaches

Note: The comparisons below are all as of February 2026. Both projects and the agent skill continue to evolve — check their repositories for the latest state.

This project is a fork of lgazo/drawio-mcp-server by Ladislav Gazo. The original acts as a bridge to a live Draw.io instance via a WebSocket browser extension for interactive, real-time diagram control. This fork is a standalone XML generator — it builds diagrams in memory and outputs Draw.io XML without needing a browser or Draw.io instance. thomast1906/github-copilot-agent-skills takes yet another approach: a Copilot Agent Skill that constructs raw Draw.io XML and sends it to the hosted mcp.draw.io service, guided by prompt instructions and a static Azure icon catalog.

All three approaches are valid — the right choice depends on whether you need interactive visual feedback (original), headless batch generation (this fork), or a zero-install agent skill.

License

MIT