{
  "markdown": "# Draw.io MCP Server\n\nThe official [draw.io](https://www.draw.io) MCP (Model Context Protocol) server that enables LLMs to create and open diagrams in the draw.io editor.\n\n## Four Ways to Create Diagrams\n\nThis repository offers four approaches for integrating draw.io with AI assistants. Pick the one that fits your setup:\n\n| | [MCP App Server](#mcp-app-server) | [MCP Tool Server](#mcp-tool-server) | [Assistant Plugins](#assistant-plugins-claude-code-codex-cli-github-copilot) | [Project Instructions](#alternative-project-instructions-no-mcp-required) |\n|---|---|---|---|---|\n| **How it works** | Renders diagrams inline in chat | Opens diagrams in your browser | Generates `.drawio` files, optional PNG/SVG/PDF export or browser URL | Claude generates draw.io URLs via Python |\n| **Diagram output** | Interactive viewer embedded in conversation | draw.io editor in a new tab | `.drawio`, `.drawio.png` / `.svg` / `.pdf`, or browser URL | Clickable link to draw.io |\n| **Requires installation** | No (hosted at `mcp.draw.io`) | Yes (npm package) | One-line plugin install (draw.io Desktop only for PNG/SVG/PDF export) | No — just paste instructions |\n| **Supports XML, CSV, Mermaid** | XML only | ✅ All three | XML only (native format) | ✅ All three |\n| **Editable in draw.io** | Via \"Open in draw.io\" button | ✅ Directly | ✅ Directly | Via link |\n| **Works with** | Claude.ai, VS Code, Cursor, any MCP Apps host | Claude Desktop, Cursor, any MCP client | Claude Code, Codex CLI, GitHub Copilot | Claude.ai (with Projects) |\n| **Best for** | Inline previews in chat | Local desktop workflows | Local development workflows | Quick setup, no install needed |\n\n---\n\n## MCP App Server\n\nThe MCP App server renders draw.io diagrams **inline** in AI chat interfaces using the [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) protocol. Instead of opening a browser tab, diagrams appear directly in the conversation as interactive iframes.\n\nThe official hosted endpoint is available at:\n\n```\nhttps://mcp.draw.io/mcp\n```\n\nAdd this URL as a remote MCP server in Claude.ai, Cursor, or any MCP Apps-compatible host — no installation required. In Cursor (≥ 2.6), diagrams render inline in the Agent chat ([one-click install](https://cursor.com/en/install-mcp?name=drawio&config=eyJ1cmwiOiJodHRwczovL21jcC5kcmF3LmlvL21jcCJ9)); on older builds, use the stdio [`@drawio/mcp`](mcp-tool-server/README.md) tool server instead.\n\nYou can also run the server locally via Node.js or deploy your own instance to Cloudflare Workers.\n\n**Tools:**\n- **`create_diagram`** — Renders draw.io XML as an interactive diagram inline in chat\n- **`search_shapes`** — Searches 10,000+ shapes across all draw.io libraries (AWS, Azure, GCP, P&ID, electrical, Cisco, Kubernetes, UML, BPMN, etc.) by keyword, supplemented by the draw.io icon service (brand logos and general-purpose concept icons) when the built-in libraries have no good match. Returns exact style strings that can be used directly in XML. Use this to find the correct shape before calling `create_diagram`.\n\n**[Full documentation →](mcp-app-server/README.md)**\n\n> **Note:** Inline diagram rendering requires an MCP host that supports the MCP Apps extension. In hosts without MCP Apps support, the tool still works but returns the XML as text.\n\n---\n\n## MCP Tool Server\n\nThe original MCP server that opens diagrams directly in the draw.io editor. Supports XML, CSV, and Mermaid.js formats with lightbox and dark mode options. Published as [`@drawio/mcp`](https://www.npmjs.com/package/@drawio/mcp) on npm.\n\nQuick start: `npx @drawio/mcp`\n\nSetup instructions are available for Claude Desktop, Claude Code, VS Code (GitHub Copilot), and Cursor (with one-click install).\n\n**[Full documentation →](mcp-tool-server/README.md)**\n\n---\n\n## Assistant Plugins (Claude Code, Codex CLI, GitHub Copilot)\n\nThe `drawio` skill packaged as a plugin for AI coding assistants (under [`plugins/`](plugins/README.md)): it generates native `.drawio` files, with optional export to PNG, SVG, or PDF (with embedded XML so the exported file remains editable in draw.io) — or a browser URL that opens the diagram directly in `app.diagrams.net`. No MCP setup required. The same skill ships for three hosts:\n\n**Claude Code** ([full documentation →](plugins/claude-code/README.md)) — install from this repo's marketplace:\n\n```\n/plugin marketplace add jgraph/drawio-mcp\n/plugin install drawio@drawio\n```\n\nOr load it directly from a local clone with `claude --plugin-dir ./plugins/claude-code`.\n\n**Codex CLI** ([full documentation →](plugins/codex/drawio/README.md)) — install from the same marketplace repo:\n\n```bash\ncodex plugin marketplace add jgraph/drawio-mcp\ncodex plugin add drawio@drawio\n```\n\n**GitHub Copilot CLI** ([full documentation →](plugins/copilot/README.md)) — install from the same marketplace repo:\n\n```bash\ncopilot plugin marketplace add jgraph/drawio-mcp\ncopilot plugin install drawio@drawio\n```\n\nOther Copilot surfaces (VS Code agent mode, the coding agent, code review) load the same skill from a repo's `.github/skills/` directory instead — see the [plugin README](plugins/copilot/README.md).\n\nBy default, the plugin writes a `.drawio` file and opens it in draw.io. Mention a format in your request to change the output:\n- **png / svg / pdf** — exports using the draw.io desktop CLI with `--embed-diagram`\n- **url** — compresses the XML with Node.js's built-in `zlib` and opens the result at `app.diagrams.net`. No draw.io Desktop needed; the `.drawio` file is kept locally as a persistent copy.\n\n---\n\n## Alternative: Project Instructions (No MCP Required)\n\nAn alternative approach that works **without installing anything**. Add instructions to a Claude Project that teach Claude to generate draw.io URLs using Python code execution. No MCP server, no desktop app — just paste and go.\n\n**[Full documentation →](project-instructions/README.md)**\n\n---\n\n## Diagram layouts\n\nTwo optional, independent layout passes can run after the AI generates a diagram — one re-arranges the nodes, the other only reroutes the edges. Which are available depends on the approach:\n\n| Layout pass | What it does | App Server (`create_diagram`) | Tool Server (`open_drawio_xml`) | Assistant Plugins | Project Instructions |\n|---|---|---|---|---|---|\n| **ELK auto-layout** (`postLayout: \"elk\"`) | Re-arranges nodes into a clean layered layout; routes the edges as part of it | ✅ | — | ✅ via draw.io Desktop CLI (`--layout`) | — |\n| **libavoid routing** (`routing: \"libavoid\"`) | Keeps node positions; reroutes connectors orthogonally *around* the shapes | ✅ | ✅ from **v1.3.0** | ✅ via draw.io Desktop CLI (`--layout libavoid`) | — |\n\n- These apply to **draw.io XML** diagrams. **Mermaid** diagrams are auto-laid-out already, so neither pass is needed.\n- The **App Server** applies these in the inline viewer after the diagram renders; the **Tool Server** applies libavoid server-side before opening the draw.io editor; the **plugins** run them through the locally installed draw.io Desktop CLI.\n- Pick one, not both: ELK already routes its own edges, so adding libavoid on top is redundant. Use `postLayout` to re-arrange a layout, or `routing` to tidy the connectors on a layout you placed deliberately.\n\n---\n\n## Data Residency & Offline Use\n\nIf you're deploying in an environment with strict data restrictions, here is exactly\nwhere diagram data goes for each approach.\n\n**No component sends your diagram to a cloud rasterizer.** `convert.diagrams.net` (or\nany cloud export endpoint) is not called anywhere in this repository, and there is no\n\"local dependency missing → fall back to cloud\" path. PNG/SVG/PDF export happens only\nin the assistant plugins, which shell out to your **locally installed draw.io Desktop CLI**\n(located via `which drawio`); if it isn't installed, the `.drawio` file is kept and\nnothing is sent.\n\n### Does your diagram leave the machine?\n\n| Approach | Diagram leaves the machine? |\n|---|---|\n| **MCP App Server — hosted (`mcp.draw.io`)** | **Yes** — it is sent to the draw.io server as the MCP request. Self-host instead (below) to keep it local. |\n| **MCP App Server — self-hosted** (local Node or your own Cloudflare) | No — processed by your server and embedded in HTML that renders client-side. |\n| **MCP Tool Server** (`@drawio/mcp`) | No — carried in the URL `#fragment`, which browsers do not transmit to the server. |\n| **Assistant Plugins** (Claude Code, Codex CLI, GitHub Copilot) | No — written locally and exported by your local draw.io Desktop CLI. |\n\nBy default the servers do not write diagram content to their logs — only request\nmetadata (method, session, status, timing). The Cloudflare-hosted App Server logs\nresponse bodies only when run with `DEBUG=true`.\n\n### Reducing external requests\n\nEven when the diagram itself stays local, the rendering loads draw.io's web-app /\nviewer **code** from `app.diagrams.net` and `viewer.diagrams.net` by default. These\nfetch application code and assets — not your diagram — but they are still outbound\nrequests. To reduce or remove them:\n\n- **App Server:** build with the `VIEWER_PATH` environment variable to inline the\n  viewer instead of loading it from `viewer.diagrams.net`.\n- **Tool Server:** set the `DRAWIO_BASE_URL` environment variable to a self-hosted\n  draw.io instance.\n- **Assistant Plugins:** the opt-in `url` output mode opens the diagram at\n  `app.diagrams.net` (hardcoded — no `DRAWIO_BASE_URL` equivalent). Use the default\n  `.drawio` output or local Desktop export instead if you need to avoid that request.\n\n### Your LLM is a separate consideration\n\nThe diagram is *generated* by the LLM. If you use a hosted model, the diagram content\nis produced in that provider's cloud regardless of where this MCP server runs.\nEnd-to-end isolation requires a locally hosted model as well.\n\n### Verifying\n\nThe only reliable way to confirm a deployment makes **no** outbound calls is to run it\nwith network egress blocked (or watch the browser's Network tab) and verify it still\nrenders. We recommend this for any strict-isolation deployment.\n\n---\n\n## XML Reference (Single Source of Truth)\n\nThe draw.io XML generation reference — covering edge routing, containers, layers, tags, metadata, dark mode, style properties, and XML well-formedness — lives in a single canonical file:\n\n**[`shared/xml-reference.md`](shared/xml-reference.md)**\n\nAll four approaches above use this file as their single source of truth for LLM prompts:\n\n| Approach | How it accesses the reference |\n|----------|-------------------------------|\n| MCP App Server | Reads the file at startup / build time and includes it in the tool description |\n| MCP Tool Server | Reads the file at startup (from repo or bundled copy via `prepack`) |\n| Assistant Plugins (Claude Code, Codex CLI, GitHub Copilot) | Reference the [GitHub raw URL](https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md) |\n| Project Instructions | Users copy its contents into their Claude Project |\n\nWhen updating XML generation guidance, edit only `shared/xml-reference.md` — changes propagate to all consumers automatically.\n\n---\n\n## Shape Search Index\n\nThe `search_shapes` tool is powered by a pre-built index of all draw.io shapes. The index is generated from the live draw.io client (`https://app.diagrams.net/js/app.min.js`) by running all sidebar palette initializations in Node.js via jsdom and capturing the shape data.\n\nIcons from the draw.io icon service (`icons.diagrams.net` — the same grouped icon search the editor sidebar uses) are **not** part of this index: `search_shapes` queries the service live when the local index has no strong match for a query, returning the icons as `shape=image` styles. Set `DRAWIO_ICON_SERVICE_URL` to a self-hosted service to override the endpoint, or to `off` to disable icon supplementation.\n\n`shape-search/search-index.json` is committed to the repository and is **automatically refreshed on every draw.io release** via the [Update Shape Search Index](.github/workflows/update-search-index.yml) GitHub Action — no manual step is required to stay in sync with the latest shapes.\n\nTo regenerate the index manually (e.g. when iterating on the generator itself):\n\n```bash\ncd shape-search\nnpm install\nnpm run generate\n\n# Rebuild the MCP App Server worker to embed the updated index\ncd ../mcp-app-server\nnpm run build:worker\n```\n\nThe generator fetches `app.min.js` directly from the public draw.io web app, so no local checkout of the draw.io source is needed.\n\n---\n\n## Development\n\n```bash\n# MCP App Server\ncd mcp-app-server\nnpm install\nnpm start\n\n# MCP Tool Server\ncd mcp-tool-server\nnpm install\nnpm start\n```\n\n## Related Resources\n\n- [draw.io](https://www.draw.io) - Free online diagram editor\n- [draw.io Desktop](https://github.com/jgraph/drawio-desktop) - Desktop application\n- [@drawio/mcp on npm](https://www.npmjs.com/package/@drawio/mcp) - This package on npm\n- [drawio-mcp on GitHub](https://github.com/jgraph/drawio-mcp) - Source code repository\n- [Mermaid.js Documentation](https://mermaid.js.org/intro/)\n- [MCP Specification](https://modelcontextprotocol.io/)\n- [MCP Apps Extension](https://modelcontextprotocol.io/docs/extensions/apps)\n",
  "bytes": 13166,
  "sha": "90c36d9696352648bcf044912a715b6198a7c2f899a11e143d3574646c108a8f",
  "repo_slug": "jgraph/drawio-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_jgraph_drawio_mcp_drawio_98f0fde3/readme"
}