drawio-mcp

kowshik24/drawio-mcp

3.1

If you are the rightful owner of drawio-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

MCP Server for Draw.io is designed to facilitate seamless integration and communication between Draw.io and other applications using the Model Context Protocol.

Draw.io Diagrams MCP

Draw.io Logo

This MCP server integrates with Draw.io diagrams, allowing you to search, view, and interact with your diagrams directly from Cursor and VS Code. Seamlessly access your architecture diagrams, flowcharts, and visual documentation without leaving your code editor.

Why Draw.io MCP?

  • Stay in your editor: Reference architectural diagrams without context switching
  • Seamless integration: Works with existing Draw.io (.drawio, .dio) files
  • Powerful search: Find diagrams by name or content
  • Automatic updates: Changes to diagram files are detected automatically
  • Recursive scanning: Automatically finds all diagrams in your workspace

Features

  • 🔍 Search Diagrams: Find diagrams based on name or content
  • 📊 View Diagrams: Load and view diagram content directly in Cursor
  • 🔄 Auto-Refresh: Automatically detect changes to diagram files
  • 📂 Recursive Scanning: Scan directories and subdirectories for Draw.io files
  • 🔄 Support for Multiple Diagram Types: Works with .drawio, .xml and .dio files

Components

Tools

  • search: Search for diagrams based on name or content

    • Parameters:
      • query (string): Search query
      • limit (number, optional): Maximum results to return (default: 50)
      • sort (string, optional): Sort order - "relevance", "name", or "lastModified" (default: "relevance")

  • retrieve: Get diagram content by ID

    • Parameters:
      • id (string): Format is "filePath#diagramId"

  • watch: Watch diagram files for changes

    • Parameters:
      • paths (array): Array of file paths to watch

  • list: List all available diagrams

    • Parameters:
      • limit (number, optional): Maximum results to return (default: 100)
      • offset (number, optional): Offset for pagination (default: 0)

  • list: List all available diagrams

    • Parameters:
      • limit (number, optional): Maximum results to return (default: 100)
      • offset (number, optional): Results to skip (default: 0)

Resources

The server provides access to Draw.io diagrams:

  • Files (drawio:///<file_path>#<diagram_id>)
    • Supports .drawio, .xml and .dio file formats
    • Parses diagram content for AI-assisted interactions
    • Provides diagram metadata including name, ID, and structure

Getting Started

Prerequisites

  • Node.js v14+
  • Draw.io diagrams (.drawio files)

Installation

Option 1: One-Click Installation (Recommended)

  1. Start the Draw.io MCP server using the instructions below
  2. Click the "Install in Cursor" button above or use the automatically generated link when you start the server

Option 2: Manual Installation

# Clone the repository
git clone https://github.com/kowshik24/drawio-mcp.git
cd drawio-mcp

# Install dependencies
npm install

# Start the server
npm run serve

After starting the server, you'll see installation links in the console. Use these links to install the MCP in Cursor or VS Code. Alternatively, you can configure Cursor manually with the provided configuration.

Option 3: For Cursor MCP Board Users

If this MCP is listed on the Cursor MCP Board, you can install it directly from there:

  1. Open Cursor
  2. Go to Settings > MCP
  3. Find "Draw.io Diagrams MCP" in the list
  4. Click Install

Usage

Starting the Server

# Start the MCP server
npm run serve

# Start with custom options
node cli.js serve --port 4000

# Scan a directory for Draw.io diagrams
npm run scan

# Scan recursively
node cli.js scan ~/diagrams --recursive

# Generate installation links
node cli.js install

API Endpoints

  • GET /mcp - Information about the MCP server
  • POST /mcp - MCP protocol endpoint
  • GET /mcp/health - Health check
  • GET /mcp/scan - Scan for diagrams
  • GET /mcp/stats - Get statistics about cached diagrams

Testing

Test API Script

The repository includes a test script for verifying the MCP API endpoints:

# Install dependencies if you haven't already
npm install

# Test all methods using npm scripts
npm test

# Test specific methods
npm run test:list
npm run test:search
npm run test:retrieve

# Or use the test script directly
node test-api.js
node test-api.js search '{"query": "test"}'
node test-api.js retrieve '{"id": "/path/to/diagram.drawio#1"}'
node test-api.js watch '{"paths": ["/path/to/diagram.drawio"]}'

Debug Mode

If you're having issues with the server, you can run it in debug mode:

# Start the server in debug mode
npm run debug

# Test with curl
curl -X POST http://localhost:3000/mcp -H "Content-Type: application/json" -d '{"method":"list","params":{}}'

The debug server provides more detailed logging to help diagnose issues with method registration and execution.

Troubleshooting

If you encounter errors with specific methods:

  1. Make sure the server is running (npm run serve)
  2. Check that there are diagrams in the cache (GET /mcp/stats)
  3. Scan for diagrams if needed (GET /mcp/scan?recursive=true)
  4. Try the server in debug mode (npm run debug)
  5. Try the test script with different parameters
  6. Check the server logs for detailed error messages

Integrating with Cursor

Method 1: One-click Installation

To install this MCP server in Cursor, start the server and then click the installation link that appears in the console, or click the badge at the top of this README.

Method 2: Manual Configuration

Add the following to your Cursor configuration:

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

Usage with VS Code

For quick installation, use the one-click install button at the top of this README.

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code:

{
  "mcp": {
    "servers": {
      "drawio": {
        "command": "node",
        "args": [
          "/path/to/drawio-mcp/index.js",
          "serve"
        ]
      }
    }
  }
}

Examples

With this MCP server, you can interact with your Draw.io diagrams in Cursor:

  • "Explain this flowchart in the diagram"
  • "What components are in this architecture diagram?"
  • "Suggest improvements to this user flow"
  • "Help me understand the relationships between components in this diagram"

Docker Support

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install --production

COPY . .

EXPOSE 3000

ENTRYPOINT ["node", "cli.js", "serve"]

To use with Docker:

# Build the Docker image
docker build -t drawio-mcp .

# Run the container
docker run -p 3000:3000 -v $(pwd)/diagrams:/app/diagrams drawio-mcp

Docker configuration for Cursor:

{
  "mcpServers": {
    "drawio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "3000:3000",
        "drawio-mcp"
      ]
    }
  }
}

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.