next-ai-draw-io/packages/mcp-server/README.md

# Next AI Draw.io MCP Server

An MCP server that lets Claude Code, Cursor, VS Code and other AI agents draw draw.io diagrams from your project's files, with a live preview in your browser. The preview is the canvas of the [Next AI Draw.io web app](https://next-ai-drawio.jiang.jp/): the AI's changes are outlined, Ctrl+Z takes them back, and you can edit by hand at any time.

https://github.com/user-attachments/assets/6f53a67b-ab21-4113-9fee-7fb32f9de678

## Install

### Let your AI agent install it

Paste this into Claude Code, Codex, Cursor, VS Code, Cline or any agent that can edit files and run commands:

```text
Install the drawio MCP server for the client you are running in, following
https://raw.githubusercontent.com/DayuanJiang/next-ai-draw-io/main/packages/mcp-server/README.md
Name the server "drawio" and keep the servers that are already configured.
Then tell me how to reload so its tools show up.
```

### Install by hand

**Claude Code**

```bash
claude mcp add drawio -- npx @next-ai-drawio/mcp-server@latest
```

**Codex CLI**

```bash
codex mcp add drawio -- npx @next-ai-drawio/mcp-server@latest
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "drawio": { "type": "stdio", "command": "npx", "args": ["@next-ai-drawio/mcp-server@latest"] }
  }
}
```

**Cursor, Claude Desktop, Cline and most other clients** (`~/.cursor/mcp.json`, `claude_desktop_config.json`, `cline_mcp_settings.json`)

```json
{
  "mcpServers": {
    "drawio": { "command": "npx", "args": ["@next-ai-drawio/mcp-server@latest"] }
  }
}
```

Restart the client, then ask, for example, "Read this repo and draw its architecture". The preview opens in your browser and the diagram appears as it is drawn.

## Features

- **Draws from your project**: the agent reads your code and documents with its own tools. Existing `.drawio` and `.drawio.svg` files open with `load_diagram`.
- **The web app's canvas**: the AI's changes are outlined and one Ctrl+Z takes them back. Select shapes and say "these" (`get_selection`). Your hand edits are read before the AI edits again.
- **Real icons**: the web app's drawing rules and shape libraries (AWS, Azure, GCP, Kubernetes, Cisco and more), so the AI uses real icon names.
- **Self-check**: the AI can look at a screenshot of the rendered diagram and fix overlaps (`screenshot: true`, or `screenshot_diagram`).
- **Versions**: the last 20 versions as cards next to the canvas; restore or compare one, or ask the AI to undo (`restore_version`).
- **Pages and export**: multi-page diagrams; save as `.drawio`, `.png`, `.svg` or `.drawio.svg`.
- **Offline**: the draw.io editor ships inside the package.

## Saved diagrams

Every change is saved to `~/.next-ai-drawio/<session-id>.drawio` with its last 20 versions; the newest 50 diagrams are kept. To continue one in a later conversation, ask the AI for it: it finds it with `list_saved_diagrams` and reopens it with `start_session`.

## Your own drawing rules

Write them in `~/.next-ai-drawio/instructions.md`, for example "Always use a minimal style". They are added to the drawing guide on every call, so edits apply without a restart. The first 5000 characters are used.

## Tools

| Tool | What it does |
|---|---|
| `start_session` | Open the preview and return the drawing guide; `session_id` continues a saved diagram |
| `create_new_diagram` | Draw a new diagram from `mxCell` XML |
| `edit_diagram` | Add, update or delete cells by id, all or nothing |
| `get_diagram` | The current XML, including your edits in the browser |
| `get_selection` | The shapes you selected in the preview |
| `screenshot_diagram` | A PNG of a page, for the AI to check |
| `load_diagram`, `export_diagram` | Open a `.drawio` or `.drawio.svg` file; save `.drawio`, `.png`, `.svg` or `.drawio.svg` |
| `restore_version` | Go back to an earlier version; a redo stays possible |
| `list_saved_diagrams` | Diagrams saved by earlier sessions, newest first |
| `get_drawing_guide`, `get_shape_library` | The drawing rules again; the icon styles of a library such as `aws4` |
| `list_pages`, `add_page`, `rename_page`, `delete_page` | Pages (tabs) |

## Configuration

Environment variables, set in the client's `env` for the server:

| Variable | Default | What it does |
|---|---|---|
| `PORT` | `6002` | Preview port; when it is taken, the next free one up to 6020 is used |
| `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for saved diagrams and `instructions.md`; `off` turns saving off |
| `DRAWIO_AUTO_SCREENSHOT` | unset | `true` attaches a screenshot to every create and edit result (2 to 10 s per call) |
| `DRAWIO_BASE_URL` | the bundled draw.io | Use another draw.io, such as a self-hosted one (see below) |
| `DRAWIO_LANG` | unset | Fix the editor and preview language: `en`, `zh`, `zh-tw`, `ja`, `de` and so on |
| `DRAWIO_UI` | unset | Fix the draw.io theme: `kennedy`, `atlas`, `dark`, `min`, `sketch` or `simple` |
| `DRAWIO_DARK` | `auto` | `1` starts dark, `0` starts light, `auto` follows the system |
| `BROWSER` | unset | `none` does not open the preview by itself; `start_session` still returns the URL |
| `DRAWIO_PREVIEW_UI` | `shell` | `classic` opens the previous preview page, without outlines, Ctrl+Z or `get_selection` |
| `DEBUG` | unset | `true` logs debug messages to stderr |

### Self-hosted draw.io

```bash
docker run -d -p 8080:8080 jgraph/drawio
```

Then set `DRAWIO_BASE_URL=http://localhost:8080`. The preview cannot reach into a draw.io from another origin, so the AI's changes are not outlined, Ctrl+Z does not take them back (use the version cards) and `get_selection` does not work. The bundled copy has no image proxy and leaves out a few features that load code on demand; see [Offline deployment](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docs/en/offline-deployment.md).

## Troubleshooting

- **Blank preview in VS Code Simple Browser or Cursor's browser**: the page refuses to be embedded in other pages. Open the URL in a regular browser.
- **Screenshot or PNG/SVG export times out**: the preview tab renders them, and browsers slow down background tabs. Bring the tab to the front and try again.
- **"No active session"**: the AI has to call `start_session` first.
- **The preview does not update**: open the URL that `start_session` returned; its `?mcp=` part connects the page to the session.

## How it works

The server talks to the agent over stdio and runs an HTTP server on `127.0.0.1` that serves the preview page and the bundled draw.io; the page polls it for changes. Every `/api` request needs a token that only the preview page has, so other websites cannot read or change your diagram.

## License

Apache-2.0