# drawio-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue?logo=typescript)](https://www.typescriptlang.org/)

An MCP (Model Context Protocol) server that enables LLMs to create and open diagrams in [draw.io](https://app.diagrams.net). Supports native draw.io XML, Mermaid.js syntax, and CSV data formats.

When an LLM calls one of the tools, the server compresses the diagram content, builds a draw.io URL with the `#create` hash parameter, and opens it in your default browser — the diagram appears instantly in the draw.io editor, ready to edit and export.

![Demo](demo.svg)

## Tools

| Tool | Format | Best for |
|------|--------|----------|
| `open_drawio_xml` | draw.io XML | Full control over styling and layout |
| `open_drawio_mermaid` | Mermaid.js | Quick flowcharts, sequence diagrams, ER diagrams |
| `open_drawio_csv` | CSV | Org charts and diagrams from tabular data |

## Installation

```bash
git clone https://github.com/mingrath/drawio-mcp.git
cd drawio-mcp
npm install
npm run build
```

Or install globally:

```bash
npm install -g drawio-mcp
```

## Configuration

### Claude Code

Add to your `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "drawio-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/drawio-mcp/dist/index.js"]
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "drawio-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/drawio-mcp/dist/index.js"]
    }
  }
}
```

## Usage Examples

### XML — Custom styled diagram

```xml
<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="2" value="Service A" style="rounded=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
      <mxGeometry x="100" y="100" width="140" height="60" as="geometry"/>
    </mxCell>
    <mxCell id="3" value="Service B" style="rounded=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
      <mxGeometry x="320" y="100" width="140" height="60" as="geometry"/>
    </mxCell>
    <mxCell id="4" style="endArrow=block;endFill=1;" edge="1" source="2" target="3" parent="1">
      <mxGeometry relative="1" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>
```

### Mermaid — Flowchart

```
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

### Mermaid — Sequence diagram

```
sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: POST /users
    API->>DB: INSERT user
    DB-->>API: OK
    API-->>Client: 201 Created
```

### CSV — Org chart

```csv
# label: %name%
# style: whiteSpace=wrap;html=1;rounded=1;fillColor=#dae8fc;strokeColor=#6c8ebf;
# connect: {"from":"manager","to":"name","invert":true,"style":"endArrow=blockThin;endFill=1;"}
# layout: auto
name,manager
CEO,
CTO,CEO
CFO,CEO
VP Engineering,CTO
VP Product,CTO
```

### Tool parameters

All three tools accept these optional parameters:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `content` | string | *(required)* | Diagram content or a URL pointing to content |
| `lightbox` | boolean | `false` | Open in read-only lightbox mode |
| `dark` | `"auto"` \| `"true"` \| `"false"` | `"auto"` | Dark mode setting |

## How It Works

1. The LLM calls a tool with diagram content (XML, Mermaid, or CSV).
2. The server URI-encodes and deflate-compresses the content.
3. A draw.io URL is constructed with the compressed data in a `#create=` hash fragment.
4. The URL opens in your default browser — draw.io reads the hash and renders the diagram.

Because the data lives in the URL hash fragment, it is never sent to any server.

## Development

```bash
npm run dev    # Watch mode — recompiles on changes
npm run build  # One-time build
npm start      # Run the compiled server
```

## Requirements

- Node.js >= 18
- A browser (for opening diagrams)

## License

[MIT](LICENSE) - Mingrath Mekavichai