Draw.io MCP Server for Agent-Controlled Diagrams

What drawio-mcp-server is designed to solve

drawio-mcp-server addresses the gap between an AI assistant and a visual diagramming application. Instead of asking an agent to emit diagram XML or describe a diagram for a human to rebuild, the server exposes MCP tools that can create, read, update, and delete diagram elements. The intended users are teams that want assistants to produce architectural diagrams, flowcharts, and visual documentation while working through an MCP client such as Claude Code, Claude Desktop, Zed, Codex, or OpenCode.

The project supports two operating paths. The built-in editor hosts Draw.io in the server's browser interface and requires no browser extension. The browser-extension path connects the MCP server to Draw.io already open in a browser, but it requires the separate drawio-mcp-extension package and a browser session with Draw.io available. This distinction matters because the extension is useful when an existing Draw.io tab is part of the workflow, while the built-in editor is the documented out-of-the-box path.

The project is not limited to adding a few rectangles and labels. Its tool surface includes document discovery, diagram inspection, shape and edge modification, layers, pages, document persistence, XML and image import or export, Mermaid diagrams, and stencil discovery for AWS, GCP, Azure, Cisco19, and CiscoSafe shapes. Multi-document and multi-page targeting are designed for workflows where an agent must direct changes to a specific tab or page rather than the currently focused view.

MCP routing and Draw.io editing architecture

The central mechanism is an MCP server backed by Draw.io editing capabilities. An MCP host starts the server, the server hosts or connects to the editor, and later tool calls are routed to connected Draw.io document instances. The README documents `list-documents` for discovery and a `target_document` selector for multi-tab workflows. Page-scoped operations use a required `target_page` selector, while `list-pages` and `get-current-page` expose page state. This creates an explicit addressing model for agents working across several files or pages.

The server also serializes live operations per document in FIFO order. The stated purpose is to let multiple agents work on different files safely, because operations affecting one document are ordered while another document can be handled independently. Page operations include `create-page`, `copy-page`, and `rename-page`. The documentation says these operations can avoid forcing a visible page switch on supported runtimes, which matters for automation that needs to modify a page without depending on what the user currently sees.

Diagram data can move between formats. The server supports import and export of XML, SVG with embedded XML, and PNG with embedded XML. Mermaid diagrams can be imported, embedded, or expanded. Edge geometry includes waypoints and automatic self-connector routing, while parent-child relationships support nested shapes and grouping. Vendor stencils are discovered at runtime from Draw.io's sidebar, so the agent can use identifiers such as `mxgraph.gcp2.cloud_run` and `mxgraph.cisco19.router` without a separately maintained catalog.

The repository is a monorepo containing the server and browser plugin. Its root package identifies the project as TypeScript and private, while the package scripts include workspace-wide build, development, test, translation, and release-check tasks. The repository also contains a Dockerfile for a multi-stage server build, although the excerpted Dockerfile does not document the complete runtime invocation.

Installing drawio-mcp-server and opening the first editor

The documented requirements are Node.js v22 or higher and an MCP client. The README says the built-in editor has no additional requirements and runs with the `--editor` flag. The preferred package manager is pnpm, although npm also works.

For Claude Code, the fastest documented path is to add the repository as a plugin marketplace and install the plugin. Run these commands in the Claude Code host:

/plugin marketplace add lgazo/drawio-mcp-server
/plugin install drawio

The README says this provides `/drawio-open` and `/drawio-status` slash commands. Restart the MCP host after configuration, then open the editor at `http://localhost:3000/`.

For other supported hosts, use the installer with one of the documented host identifiers:

npx drawio-mcp-server install <host>

Replace `<host>` with `claude-code`, `claude-desktop`, `codex`, `zed`, `opencode`, or `all`. The installer writes the MCP configuration for the selected host. After restarting that host, open `http://localhost:3000/` and issue a diagramming request such as "Create a CRUD API diagram with a database, API gateway, and four microservices with their endpoints". The expected result is an agent-controlled Draw.io document, not a static image generated outside the editor.

A manual Claude Desktop configuration is also documented. The JSON below runs the package through npx and enables the built-in editor:

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "drawio-mcp-server", "--editor"]
    }
  }
}

The README points to `CONFIG.md` for other clients and pnpm options. It does not document a separate browser-extension installation procedure in the excerpt, so that path should be followed through `packages/drawio-mcp-extension/README.md`.

Persistence, pages, Mermaid, and export formats

The document and page tools make the server more suitable for multi-step work than a single-request diagram generator. `set-document-title` and `save-document` provide explicit persistence operations. `list-documents` identifies connected instances, and `target_document` lets a later call choose one. For diagrams with multiple pages, `target_page` is required by page-scoped tools. `list-pages`, `get-current-page`, `create-page`, `copy-page`, and `rename-page` cover common page organization tasks.

This model is especially relevant to the documented example of three agents working on separate pages for service topology, message flow, and retry or failure handling. The page selector gives each operation an explicit destination. It does not make the agents autonomous or guarantee correct diagrams, but it prevents a page-scoped request from being left ambiguous in a multi-page document.

The server also recognizes Mermaid input and can import, embed, or expand it. That makes it possible to combine a textual diagram specification with direct Draw.io editing. For interchange, the format support includes native XML, SVG with embedded XML, and PNG with embedded XML. The embedded XML is significant because an exported image can retain diagram data, although the README does not describe a separate synchronization process for editing that embedded data later.

Layers provide another level of organization. The server can create, switch, and organize layers, and one README example asks an assistant to create a `Background` layer, move decorative elements there, and create a separate annotations layer. That is a concrete use case for diagrams where visual structure needs to remain separate from functional nodes and labels.

TLS, browser support, and deployment boundaries

The server supports TLS mode for HTTPS and WSS connections. According to the README, this mode can use a manually supplied certificate and key or automatically generate self-signed material through a per-user local CA. TLS is therefore an available deployment option, but the documentation excerpt does not give a complete certificate-generation command, host trust procedure, or reverse-proxy example. An operator would need to consult `CONFIG.md` for the exact configuration before exposing the service.

Firefox support is documented as restored since v2.1.0, with TLS mode described as necessary. That statement is more specific than a general browser compatibility claim, but it does not establish every supported operating system or browser version. The built-in editor is the least dependent route because the README says it has no additional requirements beyond the server runtime and MCP host.

The Docker repository entry indicates a distroless container build based on `node:26.7.0-alpine3.24`, Corepack, and pnpm. It installs dependencies, builds several workspace packages in order, and then prepares a runtime image. The excerpt does not show the final `CMD` or `ENTRYPOINT`, so a container deployment should not be treated as complete based on the repository listing alone. The documented local quick start remains the clearest first use.

The project is not archived, and the repository records its last push as 2026-10-13. Recent releases listed in the README include v2.3.0 on 2026-09-15, v2.2.0 on 2026-07-02, and v2.1.1 on 2026-06-02. The MIT license permits use and modification under its terms, but license compliance and third-party dependency obligations remain the user's responsibility.

Known limitations and the MCP alternative

The clearest limitation is the desktop application path. The README says integration with the Draw.io desktop Electron app is in progress but currently blocked by an upstream CSP issue. Users who specifically need to automate the Electron application should not select this project based on the built-in browser editor alone.

There is another workflow boundary between the built-in editor and the browser extension. The built-in path avoids extension setup, while the extension path requires `drawio-mcp-extension` and Draw.io open in a browser. The documentation does not claim that the two modes are interchangeable in every MCP runtime, so the chosen host and browser session should be checked before committing to an automation workflow.

A real alternative is to have an MCP client work with Draw.io through a browser automation layer instead of this project. The difference is architectural. A browser automation approach operates through the visible Draw.io application and its UI, whereas drawio-mcp-server defines diagram-specific MCP tools, explicit document and page selectors, built-in editor hosting, and structured inspection and modification operations. The project therefore offers a domain-specific control surface, but it also depends on its server, editor connection, and MCP client configuration. The repository documentation does not provide a comparative benchmark or claim that this approach is faster or more reliable than browser automation.

Editorial conclusion

Adopt drawio-mcp-server when an MCP host needs to create or edit Draw.io diagrams in a browser and the built-in editor fits the workflow. Do not treat it as a confirmed desktop Electron integration, since the documentation says that support is blocked by an upstream CSP issue. Check the host configuration, Node.js version, target-page selectors, and TLS requirements before deployment; the concrete first verification is opening the built-in editor at http://localhost:3000/ after configuring the MCP host.

Frequently asked questions

Official sources

1. Issues
2. lgazo/drawio-mcp-server on GitHub
3. License: MIT
4. README
5. Releases