Draw.io Skill for Claude, Gemini & Codex

Note: This skill was created using skill-seekers to convert the next-ai-draw-io project into a Claude Code skill format.

English | 中文文档 | 📚 Documentation

An MCP skill that enables AI-powered diagram creation and editing with real-time browser preview. Works with Claude Desktop, Gemini CLI, and Codex.

✨ Features

• 🎨 Natural Language → Diagram: Describe what you need, get a professional diagram
• 🔄 Real-time Preview: See changes instantly in your browser
• 📊 Multiple Diagram Types: Flowcharts, architecture diagrams, sequence diagrams, and more
• ☁️ Cloud Architecture Support: AWS, GCP, and Azure with official icons
• ✏️ Edit Existing Diagrams: Modify diagrams using ID-based operations
• 💾 Export: Save diagrams as .drawio files
• 🎬 Animated Connectors: Create dynamic and animated connectors between elements
• 📚 Version History: Restore previous diagram versions with visual thumbnails

🔗 Relationship with Upstream Project

This skill is built on top of next-ai-draw-io by @DayuanJiang.

| Project | Purpose | |---------|---------| | next-ai-draw-io | MCP Server that provides draw.io diagram tools | | This Project (drawio-skills) | MCP skill that wraps the MCP server with workflow guidance, XML format references, and diagram examples. Compatible with Claude Desktop, Gemini CLI, and Codex |

What This Skill Adds

• ✅ Comprehensive Documentation: Detailed guides for creating various diagram types
• ✅ XML Format Reference: Complete documentation of draw.io XML format and style properties
• ✅ Diagram Examples: Ready-to-use examples for flowcharts, architecture diagrams, and more
• ✅ MCP Tools Reference: Detailed documentation of all available MCP tools
• ✅ Automatic MCP Configuration: Pre-configured .mcp.json for seamless integration
• ✅ Installation Scripts: Easy setup for Windows, Linux, and macOS

📦 Installation

Prerequisites

• Node.js (for npx command)
• One of the following AI platforms:
  • Claude Desktop
  • Gemini CLI
  • Codex CLI

Quick Install

Step 1: Clone the repository

git clone https://github.com/bahayonghang/drawio-skills.git
cd drawio-skills

Step 2: Copy to your AI platform's config directory

Choose your platform and run the corresponding command:

For Claude Desktop

macOS:

cp -r skills/drawio ~/Library/Application\ Support/Claude/skills/

Windows (PowerShell):

Copy-Item -Recurse skills/drawio "$env:APPDATA\Claude\skills\"

Linux:

cp -r skills/drawio ~/.config/Claude/skills/

Then add to claude_desktop_config.json:

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["--yes", "@next-ai-drawio/mcp-server@0.1.15"]
    }
  }
}

For Gemini CLI

macOS:

cp -r skills/drawio ~/Library/Application\ Support/gemini/skills/

Windows (PowerShell):

Copy-Item -Recurse skills/drawio "$env:APPDATA\gemini\skills\"

Linux:

cp -r skills/drawio ~/.gemini/skills/

Then add to settings.json:

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["--yes", "@next-ai-drawio/mcp-server@0.1.15"]
    }
  }
}

For Codex

All platforms:

cp -r skills/drawio ~/.codex/skills/

Then add to ~/.codex/config.toml:

[mcp_servers.drawio]
command = "npx"
args = ["--yes", "@next-ai-drawio/mcp-server@0.1.15"]

The skill will be available automatically after restarting your AI client.

🚀 Usage

Once the skill is installed, simply ask Claude to create a diagram:

Basic Examples

"Create a flowchart for user login process"

"Draw a three-tier architecture diagram"

"Generate a microservices architecture for an e-commerce system"

🎯 Real Example: E-Commerce Microservices Architecture

⚠️ Note: This example is for reference only. The current workflow may have some issues (e.g., element overlapping). We are actively optimizing the workflow to improve diagram generation quality.

Prompt used:

Design a microservices e-commerce system architecture diagram with the following components:

API Gateway
├── User Service (authentication, user profiles)
├── Product Catalog Service (inventory management, product search, categories)
├── Shopping Cart Service (cart management, session handling)
├── Order Service (order processing, order history)
├── Payment Service (payment gateway, transactions)
└── Notification Service (emails, SMS, push notifications)

Infrastructure:
- API Gateway (entry point for all requests)
- Service Mesh (service-to-service communication)
- Message Queue (RabbitMQ/Kafka for async events)
- Cache Layer (Redis for session and product caching)
- Databases (PostgreSQL per service)
- CDN/Load Balancer
- Monitoring (Prometheus, Grafana)

Result: examples/ecommerce-microservices.drawio

This example demonstrates:

• ✅ Clear layering (KISS principle): Client → CDN → API Gateway → Microservices → Database
• ✅ Service independence (SOLID): Each service has its own database
• ✅ Async communication: Message queue for order/payment → notification events
• ✅ Observability: Prometheus + Grafana monitoring
• ✅ Optimized routing: Non-overlapping connection lines with Chinese labels

Advanced Examples

AWS Architecture

"Generate an AWS architecture diagram with Lambda, API Gateway, DynamoDB,
and S3 for a serverless REST API. Use AWS icons."

GCP Architecture

"Generate a GCP architecture diagram with Cloud Run, Cloud SQL, and
Cloud Storage for a web application. Use GCP icons."

Sequence Diagram

"Create a sequence diagram showing OAuth 2.0 authorization code flow
between user, client app, auth server, and resource server"

Animated Connectors

"Give me an animated connector diagram of transformer's architecture"

🛠️ MCP Tools

This skill uses the following MCP tools from @next-ai-drawio/mcp-server:

| Tool | Purpose | |------|---------| | start_session | Open browser with real-time preview | | create_new_diagram | Create new diagram from XML | | get_diagram | Retrieve current diagram XML | | edit_diagram | Modify diagram by cell ID | | export_diagram | Save as .drawio file |

For detailed documentation of each tool, see references/mcp-tools.md.

📖 Documentation

References

• MCP Tools Reference: Detailed documentation of all available MCP tools
• XML Format Reference: Complete guide to draw.io XML format and style properties
• Diagram Examples: Ready-to-use examples for various diagram types

Diagram Types

This skill supports creating the following diagram types:

• Flowcharts: Process flows, decision trees, workflows
• Architecture Diagrams: System architecture, microservices, deployment diagrams
• Sequence Diagrams: Interaction flows, API calls, message sequences
• Network Diagrams: Network topology, VPC architecture, security zones
• Data Flow Diagrams: Data pipelines, ETL processes, analytics workflows
• UML Diagrams: Class diagrams, state diagrams, component diagrams
• Cloud Architecture: AWS, GCP, Azure with official icons

📁 Project Structure

drawio-skills/
├── skills/
│   └── drawio/
│       ├── .mcp.json                 # MCP server configuration
│       ├── SKILL.md                  # Main skill documentation
│       ├── scripts/
│       │   ├── install.sh           # Linux/macOS installation script
│       │   └── install.bat          # Windows installation script
│       └── references/
│           ├── mcp-tools.md         # MCP tools reference
│           ├── xml-format.md        # Draw.io XML format reference
│           └── examples.md          # Diagram examples
├── README.md                         # English documentation
└── README_CN.md                      # Chinese documentation

🔧 Configuration

The skill uses the following default configuration:

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["--yes", "@next-ai-drawio/mcp-server@0.1.15"]
    }
  }
}

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 6002 | Port for the embedded HTTP server | | DRAWIO_BASE_URL | https://embed.diagrams.net | Base URL for draw.io (for self-hosted deployments) |

🐛 Troubleshooting

Port already in use

If port 6002 is in use, the server will automatically try the next available port (up to 6020).

"No active session"

Call start_session first to open the browser window.

Browser not updating

Check that the browse