drawio-mcp-server 1.7.0 → 2.0.3

package/README.md

@@ -1,518 +1,189 @@
-
 # Draw.io MCP server
 
 Let's do some Vibe Diagramming with the most wide-spread diagramming tool called Draw.io (Diagrams.net).
 
-[![Discord channel](https://shields.io/static/v1?logo=discord&message=draw.io%20mcp&label=chat&color=5865F2&logoColor=white)](https://discord.gg/dM4PWdf42q) [![Build project](https://github.com/lgazo/drawio-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/lgazo/drawio-mcp-server/actions/workflows/ci.yml) [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/5fc2b7fe-8ceb-4683-97bd-6d31e07b5888)
+[![Discord channel](https://shields.io/static/v1?logo=discord&message=draw.io%20mcp&label=chat&color=5865F2&logoColor=white)](https://discord.gg/dM4PWdf42q)
+[![Build project](https://github.com/lgazo/drawio-mcp-server/actions/workflows/server-ci.yml/badge.svg)](https://github.com/lgazo/drawio-mcp-server/actions/workflows/server-ci.yml)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/5fc2b7fe-8ceb-4683-97bd-6d31e07b5888)
+[![Version](https://img.shields.io/npm/v/drawio-mcp-server)](https://npmjs.com/package/drawio-mcp-server)
 
-## Introduction
+## Key Highlights
 
-The Draw.io MCP server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) implementation that brings powerful diagramming capabilities to AI agentic systems. This integration enables:
+- Import and export diagrams from/to XML, SVG (with embedded XML), or PNG (with embedded XML) ![v2.0.0](https://img.shields.io/badge/v2.0.0-blue)
+- Edge geometry control with waypoints and automatic self-connector routing ![v2.0.0](https://img.shields.io/badge/v2.0.0-blue)
+- Parent-child relationships for nested shapes and grouping ![v2.0.0](https://img.shields.io/badge/v2.0.0-blue)
+- Unified Server and Extension in the same mono-repo ![v2.0.0](https://img.shields.io/badge/v2.0.0-blue)
+- Built-in Draw.io editor - no browser extension required ![v1.8.0](https://img.shields.io/badge/v1.8.0-blue)
+- MCP server that lets AI agents control Draw.io diagrams
+- Programmatic diagram creation, inspection, and modification via MCP tools
+- Layer management for complex diagrams
+- Works with any MCP client (Claude Desktop, Claude Code, Zed, Codex, etc.)
 
-- **Seamless Draw.io Integration**: Connect your MCP-powered applications with Draw.io's rich diagramming functionality
-- **Programmatic Diagram Control**: Create, modify, and manage diagram content through MCP commands
-- **Intelligent Diagram Analysis**: Retrieve detailed information about diagrams and their components for processing by AI agents
-- **Agentic System Development**: Build sophisticated AI workflows that incorporate visual modeling and diagram automation
+## Introduction
 
-As an MCP-compliant tool, it follows the standard protocol for tool integration, making it compatible with any MCP client. This implementation is particularly valuable for creating AI systems that need to:
-- Generate architectural diagrams
-- Visualize complex relationships
-- Annotate technical documentation
-- Create flowcharts and process maps programmatically
+The Draw.io MCP server brings Draw.io diagramming capabilities to AI agents. It provides MCP tools that can create, read, update, and delete diagram elements - letting AI assistants build architectural diagrams, flowcharts, and visual documentation automatically.
 
-The tool supports bidirectional communication, allowing both control of Draw.io instances and extraction of diagram information for further processing by AI agents in your MCP ecosystem.
+Two ways to use:
+1. **Built-in editor** - Server hosts Draw.io directly, accessible in your browser
+2. **Browser extension** - Connect to Draw.io running in your browser via extension
 
 ## Requirements
 
-To use the Draw.io MCP server, you'll need:
-
-### Core Components
 - **Node.js** (v20 or higher) - Runtime environment for the MCP server
-- **Draw.io MCP Browser Extension** - Enables communication between Draw.io and the MCP server
+- **MCP client** - Claude Desktop, Claude Code, Zed, Codex, OpenCode, or any MCP-compatible host
 
-### MCP Ecosystem
-- **MCP Client** (e.g., [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector)) - For testing and debugging the integration
-- **LLM with Tools Support** - Any language model capable of handling MCP tool calls (e.g., GPT-4, Claude 3, etc.)
+### For Built-in Editor
+No additional requirements - runs out of the box with `--editor` flag.
 
-### Optional for Development
-- **pnpm** - Preferred package manager
-- **Chrome DevTools** - For debugging when using `--inspect` flag
+### For Browser Extension
+- **Browser extension** - [drawio-mcp-extension](./packages/drawio-mcp-extension/README.md)
+- Draw.io open in your browser
 
-Note: The Draw.io desktop app or web version must be accessible to the system where the MCP server runs.
+### Optional
+- **pnpm** - Preferred package manager (npm works fine too)
 
-## Configuration
+## Quick Start
 
-### WebSocket Port
+### 1. Configure your MCP host
 
-The server listens on port 3333 by default for WebSocket connections from the browser extension. You can customize this port using the `--extension-port` or `-p` flag.
+Add the server to your MCP client configuration:
 
-**Default behavior** (port 3333):
-```json
-{
-  "mcpServers": {
-    "drawio": {
-      "command": "npx",
-      "args": ["-y", "drawio-mcp-server"]
-    }
-  }
-}
-```
-
-**Custom port** (e.g., port 8080):
-```json
-{
-  "mcpServers": {
-    "drawio": {
-      "command": "npx",
-      "args": ["-y", "drawio-mcp-server", "--extension-port", "8080"]
-    }
-  }
-}
-```
-
-**Note**: When using a custom port, ensure the browser extension is configured to connect to the same port.
-
-### HTTP Transport Port
+<details>
+  <summary>Claude Desktop</summary>
 
-The server can expose a streamable HTTP MCP transport on port 3000. Change this using the `--http-port` flag:
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "drawio": {
       "command": "npx",
-      "args": ["-y", "drawio-mcp-server", "--transport", "http", "--http-port", "4000"]
+      "args": ["-y", "drawio-mcp-server", "--editor"]
     }
   }
 }
 ```
-
-### Transport Selection
-
-By default only the stdio transport starts. Limit or combine transports with the `--transport` flag:
-
-- `--transport stdio` – start only stdio (CLI-friendly)
-- `--transport http` – start only the HTTP transport (for remote clients)
-- `--transport stdio,http` – start both transports
-
-### Running the streamable HTTP transport
-
-Use the streamable HTTP transport when you need to reach the MCP server over the network (for example from a remote agent runtime). The Draw.io browser extension is still required, and you must opt in to the HTTP transport.
-
-1. Start the server with HTTP enabled (optionally alongside stdio):
-
-```sh
-npx -y drawio-mcp-server --transport http --http-port 3000
-# or both: npx -y drawio-mcp-server --transport stdio,http --http-port 4000
-```
-
-2. Verify the health endpoint:
-
-```sh
-curl http://localhost:3000/health
-# { "status": "ok" }
-```
-
-3. Point your MCP client to the `/mcp` endpoint (`http://localhost:3000/mcp` by default). CORS is enabled for all origins so you can call it from a browser-based client as well.
-
-## Installation
-
-### Connecting with Claude Desktop
-
-1. Install [Claude Desktop](https://claude.ai/download)
-2. Open or create the configuration file:
-   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-3. Update it to include this server:
+</details>
 
 <details>
-  <summary>Using <code>npm</code></summary>
+  <summary>Claude Code</summary>
 
-```json
-{
-   "mcpServers":{
-      "drawio":{
-         "command":"npx",
-         "args":[
-            "-y",
-            "drawio-mcp-server"
-         ]
-      }
-   }
-}
+```sh
+claude mcp add-json drawio '{"type":"stdio","command":"npx","args":["-y","drawio-mcp-server","--editor"]}'
 ```
 </details>
 
 <details>
-  <summary>Using <code>pnpm</code></summary>
-
-```json
-{
-   "mcpServers":{
-      "drawio":{
-         "command":"pnpm",
-         "args":[
-            "dlx",
-            "drawio-mcp-server"
-         ]
-      }
-   }
-}
-```
-</details>
+  <summary>Zed</summary>
 
-To use a custom extension port (e.g., 8080), add `"--extension-port", "8080"` to the args array:
+Add to `~/.config/zed/settings.json`:
 
 ```json
 {
-  "mcpServers": {
+  "context_servers": {
     "drawio": {
       "command": "npx",
-      "args": ["-y", "drawio-mcp-server", "--extension-port", "8080"]
+      "args": ["-y", "drawio-mcp-server", "--editor"],
+      "env": {}
     }
   }
 }
 ```
-
-4. Restart Claude Desktop
-
-### Connecting with oterm
-
-This is an alternative MCP client in case you like terminal and you plan to connect to your own Ollama instance.
-
-The configuration is usually in: ~/.local/share/oterm/config.json
+</details>
 
 <details>
-  <summary>Using <code>npm</code></summary>
+  <summary>Codex</summary>
 
-```json
-{
-	"mcpServers": {
-		"drawio": {
-			"command": "npx",
-			"args": [
-			  "-y",
-        "drawio-mcp-server"
-			]
-		}
-	}
-}
+Edit `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.drawio]
+command = "npx"
+args = ["-y", "drawio-mcp-server", "--editor"]
 ```
 </details>
 
 <details>
-  <summary>Using <code>pnpm</code></summary>
-
-```json
-{
-	"mcpServers": {
-		"drawio": {
-			"command": "pnpm",
-			"args": [
-			  "dlx",
-        "drawio-mcp-server"
-			]
-		}
-	}
-}
-```
-</details>
+  <summary>OpenCode</summary>
 
-To use a custom extension port (e.g., 8080), add `"--extension-port", "8080"` to the args array:
+Add to `opencode.json` in your project root or `~/.config/opencode/opencode.json`:
 
-```json
+```jsonc
 {
-  "mcpServers": {
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
     "drawio": {
-      "command": "npx",
-      "args": ["-y", "drawio-mcp-server", "--extension-port", "8080"]
+      "type": "local",
+      "command": ["npx", "-y", "drawio-mcp-server", "--editor"],
+      "enabled": true
     }
   }
 }
 ```
-
-### Connect with Zed
-
-1. Open the Zed Preview application.
-1. Click the Assistant (✨) icon in the bottom right corner.
-1. Click Settings in the top right panel of the Assistant.
-1. In the Context Servers section, click + Add Context Server.
-1. Configure with the following:
-
-<details>
-  <summary>Using <code>npm</code></summary>
-
-```json
-{
-  /// The name of your MCP server
-  "drawio": {
-	/// The path to the executable
-	"command": "npx",
-	/// The arguments to pass to the executable
-	"args": [
-	  "-y",
-	  "drawio-mcp-server"
-	],
-	/// The environment variables to set for the executable
-    "env": {}
-  }
-}
-```
 </details>
 
-<details>
-  <summary>Using <code>pnpm</code></summary>
+For other MCP clients and detailed configuration (including pnpm options), see [Configuration](./CONFIG.md).
 
-```json
-{
-  /// The name of your MCP server
-  "drawio": {
-	/// The path to the executable
-	"command": "pnpm",
-	/// The arguments to pass to the executable
-	"args": [
-	  "dlx",
-	  "drawio-mcp-server"
-	],
-	/// The environment variables to set for the executable
-    "env": {}
-  }
-}
-```
-</details>
+### 2. Open the editor
 
-To use a custom extension port (e.g., 8080), add `"--extension-port", "8080"` to the args array:
+After restarting your MCP host, open: **http://localhost:3000/**
 
-```json
-{
-  "drawio": {
-    "command": "npx",
-    "args": [
-      "-y",
-      "drawio-mcp-server",
-      "--extension-port",
-      "8080"
-    ],
-    "env": {}
-  }
-}
-```
+### 3. Start diagramming
 
-### Connecting with Codex
+Example prompts you can try:
 
-Edit the configuration usually located in: ~/.codex/config.toml
+> "Create an event-driven architecture diagram showing a message queue with producers, consumers, and three backend services"
 
-<details>
-  <summary>Using <code>npm</code></summary>
+> "Draw a CRUD API diagram with a database, API gateway, and four microservices with their endpoints"
 
-```toml
-[mcp_servers.drawio]
-command = "npx"
-args = [
-    "-y",
-    "drawio-mcp-server"
-]
-```
-</details>
+> "Add a new layer called 'Background' and move all decorative elements to it, then create a new layer for annotations"
 
-<details>
-  <summary>Using <code>pnpm</code></summary>
+Your AI assistant can now control the diagram using MCP tools.
 
-```toml
-[mcp_servers.drawio]
-command = "pnpm"
-args = [
-    "dlx",
-    "drawio-mcp-server"
-]
-```
-</details>
-
-To use a custom extension port (e.g., 8080), add `"--extension-port", "8080"` to the args array:
+## Features
 
-<details>
-  <summary>Using <code>npm</code></summary>
+The server provides MCP tools for:
 
-```toml
-[mcp_servers.drawio]
-command = "npx"
-args = [
-    "-y",
-    "drawio-mcp-server",
-    "--extension-port",
-    "8080"
-]
-```
-</details>
+- **Diagram inspection** - read shapes, layers, and cell properties
+- **Diagram modification** - add/edit/delete shapes, edges, and labels
+- **Layer management** - create, switch, and organize layers
 
-To connect to a locally running MCP with Streamable HTTP transport:
+See [Tools Reference](./TOOLS.md) for the complete list of available tools.
 
-```toml
-[mcp_servers.drawio]
-url = "http://localhost:3000/mcp"
-```
+## Installation
 
+The server runs as part of your MCP host. Detailed configuration for all supported clients (Claude Desktop, Claude Code, Zed, Codex, oterm) including npm and pnpm options is available in [Configuration](./CONFIG.md).
 
-### Browser Extension Setup
+## Alternative: Browser Extension
 
-In order to control the Draw.io diagram, you need to install dedicated Browser Extension.
+Instead of the built-in editor, you can use the [browser extension](./packages/drawio-mcp-extension/README.md) to connect to Draw.io running in your browser. This works with or without the `--editor` flag.
 
 1. Open [Draw.io in your browser](https://app.diagrams.net/)
-2. Install the Draw.io MCP Browser Extension from a web store or [use other means](https://github.com/lgazo/drawio-mcp-extension)
-<p>
-  <a href="https://chrome.google.com/webstore/detail/drawio-mcp-extension/okdbbjbbccdhhfaefmcmekalmmdjjide">
-    <picture>
-      <source srcset="https://i.imgur.com/XBIE9pk.png" media="(prefers-color-scheme: dark)" />
-      <img height="58" src="https://i.imgur.com/oGxig2F.png" alt="Chrome Web Store" /></picture
-  ></a>
-  <a href="https://addons.mozilla.org/en-US/firefox/addon/drawio-mcp-extension/">
-    <picture>
-      <source srcset="https://i.imgur.com/ZluoP7T.png" media="(prefers-color-scheme: dark)" />
-      <img height="58" src="https://i.imgur.com/4PobQqE.png" alt="Firefox add-ons" /></picture
-  ></a>
-</p>
-3. Ensure it is connected, the Extension icon should indicate green signal overlay <img alt="Extension connected" src="https://raw.githubusercontent.com/lgazo/drawio-mcp-extension/refs/heads/main/public/icon/logo_connected_32.png" />
-
-**Important**: If you configured the MCP server to use a custom port (not 3333), you must configure the browser extension to use the same port. See the extension documentation for port configuration instructions.
-
-
-## Sponsoring
-
-If you enjoy the project or find it useful, consider supporting its continued development.
+2. Install the Draw.io MCP Browser Extension:
+   - [Chrome Web Store](https://chrome.google.com/webstore/detail/drawio-mcp-extension/okdbbjbbccdhhfaefmcmekalmmdjjide)
+   - [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/drawio-mcp-extension/)
+3. Ensure the extension is connected (green signal overlay on icon)
 
+Configuration without `--editor`:
 
-lightning invoice:
-
-![lightning invoice](./lightning_qr.png)
-
-```
-lnbc1p5f8wvnpp5kk0qt60waplesw3sjxu7tcqwmdp6ysq570dc4ln52krd3u5nzq6sdp82pshjgr5dusyymrfde4jq4mpd3kx2apq24ek2uscqzpuxqr8pqsp5gvr72xcs883qt4hea6v3u7803stcwfnk5c9w0ykqr9a40qqwnpys9qxpqysgqfzlhm0cz5vqy7wqt7rwpmkacukrk59k89ltd5n642wzru2jn88tyd78gr4y3j6u64k2u4sd4qgavlsnccl986velrg3x0pe95sx7p4sqtatttp
-```
-
-lightning address:
-```
-ladislav@blink.sv
+```json
+{
+  "mcpServers": {
+    "drawio": {
+      "command": "npx",
+      "args": ["-y", "drawio-mcp-server"]
+    }
+  }
+}
 ```
 
-<div align="center">
-<a href="https://liberapay.com/ladislav/donate"><img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg"></a>
-</div>
+See the [extension documentation](./packages/drawio-mcp-extension/README.md) for more details.
 
-## Features
+## Related Resources
 
-The Draw.io MCP server provides the following tools for programmatic diagram interaction:
-
-### Diagram Inspection Tools
-- **`get-selected-cell`**
-  Retrieves the currently selected cell in Draw.io with all its attributes
-  *Returns*: JSON object containing cell properties (ID, geometry, style, value, etc.)
-
-- **`get-shape-categories`**
-  Retrieves available shape categories from the diagram's library
-  *Returns*: Array of category objects with their IDs and names
-
-- **`get-shapes-in-category`**
-  Retrieves all shapes in a specified category from the diagram's library
-  *Parameters*:
-    - `category_id`: Identifier of the category to retrieve shapes from
-  *Returns*: Array of shape objects with their properties and styles
-
-- **`get-shape-by-name`**
-  Retrieves a specific shape by its name from all available shapes
-  *Parameters*:
-    - `shape_name`: Name of the shape to retrieve
-  *Returns*: Shape object including its category and style information
-
-- **`list-paged-model`**
-  Retrieves a paginated view of all cells (vertices and edges) in the current Draw.io diagram. This tool provides access to the complete model data with essential fields only, sanitized to remove circular dependencies and excessive data. It allows to filter based on multiple criteria and attribute boolean logic. Useful for programmatic inspection of diagram structure without overwhelming response sizes.
-
-### Diagram Modification Tools
-- **`add-rectangle`**
-  Creates a new rectangle shape on the active Draw.io page with customizable properties:
-  - Position (`x`, `y` coordinates)
-  - Dimensions (`width`, `height`)
-  - Text content
-  - Visual style (fill color, stroke, etc. using Draw.io style syntax)
-
-- **`add-edge`**
-  Creates a connection between two cells (vertexes)
-  *Parameters*:
-    - `source_id`: ID of the source cell
-    - `target_id`: ID of the target cell
-    - `text`: Optional text label for the edge
-    - `style`: Optional style properties for the edge
-
-- **`delete-cell-by-id`**
-  Removes a specified cell from the diagram
-  *Parameters*:
-    - `cell_id`: ID of the cell to delete
-
-- **`add-cell-of-shape`**
-  Adds a new cell of a specific shape type from the diagram's library
-  *Parameters*:
-    - `shape_name`: Name of the shape to create
-    - `x`, `y`: Position coordinates (optional)
-    - `width`, `height`: Dimensions (optional)
-    - `text`: Optional text content
-    - `style`: Optional additional style properties
-
-- **`set-cell-shape`**
-  Applies a library shape's style to an existing cell
-  *Parameters*:
-    - `cell_id`: ID of the cell whose appearance should change
-    - `shape_name`: Name of the library shape whose style should be applied
-
-- **`set-cell-data`**
-  Stores or updates a custom attribute on a cell
-  *Parameters*:
-    - `cell_id`: ID of the cell to update
-    - `key`: Attribute name to set
-    - `value`: Attribute value (stored as a string internally)
-
-- **`edit-cell`**
-  Updates an existing vertex/shape cell in place by ID
-  *Parameters*:
-    - `cell_id`: ID of the cell whose properties should change (required)
-    - `text`, `x`, `y`, `width`, `height`, `style`: Optional fields to update on the cell; omitted properties stay as-is
-
-- **`edit-edge`**
-  Updates an existing edge connection between cells by ID
-  *Parameters*:
-    - `cell_id`: ID of the edge cell to update (required)
-    - `text`: Optional edge label text
-    - `source_id`, `target_id`: Optional IDs of new source/target cells
-    - `style`: Optional replacement style string
-
-### Layer Management Tools
-- **`list-layers`**
-  Lists all available layers in the diagram with their IDs and names
-  *Returns*: Array of layer objects with properties (ID, name, visibility, locked status)
-
-- **`set-active-layer`**
-  Sets the active layer for creating new elements. All subsequent element creation will happen in this layer
-  *Parameters*:
-    - `layer_id`: ID of the layer to set as active
-  *Returns*: Information about the newly active layer
-
-- **`move-cell-to-layer`**
-  Moves a cell from its current layer to a target layer
-  *Parameters*:
-    - `cell_id`: ID of the cell to move
-    - `target_layer_id`: ID of the target layer where the cell will be moved
-  *Returns*: Confirmation of the move operation
-
-- **`get-active-layer`**
-  Gets the currently active layer information
-  *Returns*: Information about the current active layer (ID and name)
-
-- **`create-layer`**
-  Creates a new layer in the diagram
-  *Parameters*:
-    - `name`: Name for the new layer
-  *Returns*: Information about the newly created layer
+[Configuration](./CONFIG.md) - CLI flags and advanced options
 
-## Related Resources
+[Tools Reference](./TOOLS.md) - Complete MCP tools documentation
 
 [Troubleshooting](./TROUBLESHOOTING.md)