MCP Draw.io Diagram Server

A Model Context Protocol (MCP) server that generates Draw.io compatible diagrams from natural language prompts. This server enables AI assistants to create professional diagrams in XML format that can be opened directly in Draw.io.

Features

• Flowchart Generation: Create sequential flowcharts with various shapes (process, decision, terminator, data, etc.)
• Sequence Diagrams: Generate UML sequence diagrams showing interactions between participants
• Network Diagrams: Build network and architecture diagrams with custom node positioning
• Custom Diagrams: Full control over shapes, positions, and connections for any diagram type
• Draw.io Compatible: Outputs valid Draw.io XML format that can be imported directly

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

Configuration

Environment Variables

• DRAWIO_OUTPUT_DIR: (Optional) Specifies the directory where diagram files will be saved. If not set, files are saved to the current working directory.

Example:

export DRAWIO_OUTPUT_DIR=/path/to/diagrams  # Linux/macOS
set DRAWIO_OUTPUT_DIR=C:\diagrams          # Windows

Usage with Claude Desktop

Add this server to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Basic Configuration

{
  "mcpServers": {
    "drawio-diagram": {
      "command": "node",
      "args": ["D:\\TopSecret\\diagram-master\\index.js"]
    }
  }
}

With Custom Output Directory

{
  "mcpServers": {
    "drawio-diagram": {
      "command": "node",
      "args": ["D:\\TopSecret\\diagram-master\\index.js"],
      "env": {
        "DRAWIO_OUTPUT_DIR": "C:\\Users\\YourName\\Documents\\Diagrams"
      }
    }
  }
}

Make sure to update the paths to match your actual installation directory and desired output location.

Available Tools

1. create_flowchart

Creates a sequential flowchart diagram and saves it to a file.

Parameters:

• filename: Name for the output .drawio file (extension added automatically)
• steps: Array of flowchart steps
  • label: Text for the step
  • type: Shape type (process, decision, terminator, data, document, delay)
  • connectorLabel: Optional label for the connector arrow

Example:

Create a flowchart named "login-process" for a login process with these steps:
1. Start (terminator)
2. Enter credentials (data)
3. Validate credentials (process)
4. Is valid? (decision)
5. Show dashboard (process)
6. End (terminator)

2. create_sequence_diagram

Creates a UML sequence diagram showing interactions and saves it to a file.

Parameters:

• filename: Name for the output .drawio file (extension added automatically)
• participants: Array of participant names
• interactions: Array of interactions
  • from: Source participant
  • to: Target participant
  • message: Interaction message
  • dashed: Use dashed line for returns (optional)

Example:

Create a sequence diagram named "api-request" for an API request with participants: Client, API Server, Database
Show these interactions:
- Client sends "GET /users" to API Server
- API Server sends "SELECT * FROM users" to Database
- Database returns "User data" to API Server (dashed)
- API Server returns "200 OK" to Client (dashed)

3. create_network_diagram

Creates a network or architecture diagram with positioned nodes and saves it to a file.

Parameters:

• filename: Name for the output .drawio file (extension added automatically)
• nodes: Array of network nodes
  • id: Unique identifier
  • label: Display label
  • type: Shape type (rectangle, cylinder, database, cloud, hexagon, ellipse)
  • x, y: Position coordinates
  • width, height: Optional dimensions
• connections: Array of connections
  • from: Source node ID
  • to: Target node ID
  • label: Connection label (optional)

Example:

Create a network diagram named "web-architecture" showing:
- Web Server (rectangle) at position 100, 100
- Application Server (rectangle) at position 300, 100
- Database (database/cylinder) at position 500, 100
Connect them in sequence with labeled connections

4. create_custom_diagram

Creates a custom diagram with full control over all elements and saves it to a file.

Parameters:

• filename: Name for the output .drawio file (extension added automatically)
• shapes: Array of shapes
  • id: Unique identifier for connections
  • label: Text label
  • type: Shape type (see supported shapes below)
  • x, y: Position
  • width, height: Optional dimensions
• connectors: Array of connectors (optional)
  • from: Source shape ID
  • to: Target shape ID
  • label: Connector label (optional)

Supported shape types:

• rectangle, roundedRectangle, ellipse, diamond
• parallelogram, cylinder, hexagon, cloud
• document, process, decision, data
• terminator, database, actor, note

Example Prompts

Here are some example prompts you can use with Claude:

1. Simple Flowchart:

   Create a flowchart named "password-reset" for password reset: Start -> Enter Email -> Send Reset Link -> Check Email -> Reset Password -> End
   

2. System Architecture:

   Create a network diagram named "web-architecture" showing a three-tier web architecture with load balancer, web servers, app servers, and database
   

3. UML Sequence:

   Create a sequence diagram named "user-auth" for user authentication with User, Frontend, Auth Service, and Database
   

4. Custom Business Process:

   Create a custom diagram named "order-process" showing an order processing workflow with decision points for inventory check and payment validation
   

Output Format

The server automatically saves diagrams as .drawio files in the configured output directory (or current working directory if not configured).

To use the generated diagrams:

1. The server will report the full path where the file was saved
2. Open the .drawio file directly in Draw.io (https://app.diagrams.net)
3. Edit, export, or share the diagram as needed

File Naming:

• Files are automatically saved with the .drawio extension
• If you specify filename: "my-diagram", it will be saved as my-diagram.drawio
• The .drawio extension is added automatically if not present

Development

Project Structure

diagram-master/
├── index.js              # MCP server implementation
├── drawio-generator.js   # Draw.io XML generation utilities
├── package.json          # Project dependencies
└── README.md            # This file

Running Standalone

While this is designed as an MCP server, you can test the diagram generation directly:

import { DrawioGenerator } from './drawio-generator.js';

const generator = new DrawioGenerator();

const steps = [
  { label: 'Start', type: 'terminator' },
  { label: 'Process Data', type: 'process' },
  { label: 'End', type: 'terminator' }
];

const xml = generator.createFlowchart(steps);
console.log(xml);

Troubleshooting

Server not appearing in Claude:

• Verify the path in claude_desktop_config.json is correct
• Ensure Node.js 18+ is installed
• Check that npm install completed successfully
• Restart Claude Desktop after configuration changes

Diagrams not opening in Draw.io:

• Ensure you saved the file with .drawio extension
• Verify the XML is complete (starts with <?xml and ends with </mxfile>)
• Try importing via File > Import in Draw.io

License

MIT

Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

Roadmap

Future enhancements:

• More diagram types (ERD, class diagrams, state machines)
• Style customization (colors, fonts, line styles)
• Layout algorithms for automatic positioning
• Template library for common diagram patterns
• Export to multiple formats (PNG, SVG, PDF)