# OpenFlowKit MCP server

> Allows AI agents to draw, edit, and manage architecture diagrams on a live canvas or via code files.

- Repository: https://github.com/Vrun-design/openflowkit
- Page: https://hostedmcp.org/servers/vrun-design/openflowkit
- Transport: stdio
- Stars: 981
- License: MIT
- Latest version: 0.2.1

## Install

### Claude Code

```sh
claude mcp add openflowkit -- npx -y @vrun-design/openflowkit-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "openflowkit": {
      "command": "npx",
      "args": [
        "-y",
        "@vrun-design/openflowkit-mcp"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "openflowkit": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@vrun-design/openflowkit-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"openflowkit","type":"stdio","command":"npx","args":["-y","@vrun-design/openflowkit-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "openflowkit": {
      "command": "npx",
      "args": [
        "-y",
        "@vrun-design/openflowkit-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add openflowkit -- npx -y @vrun-design/openflowkit-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.openflowkit]
command = "npx"
args = ["-y", "@vrun-design/openflowkit-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user openflowkit npx -- -y @vrun-design/openflowkit-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "openflowkit": {
      "command": "npx",
      "args": [
        "-y",
        "@vrun-design/openflowkit-mcp"
      ]
    }
  }
}
```

## Tools (29)

- `validate_openflow_dsl`: Parse and compile OpenFlow DSL — or Mermaid, Structurizr DSL or D2, converted first — and return structured diagnostics (code, severity, line, column, message, hint), the same check as `openflowkit validate`. `ok` is false on any error: text that cannot be drawn, or a line the parser could not read (create_diagram would draw without it). Warnings name guesses (an unknown word, a misspelled header) that still draw. For another language, `converted.dsl` is what it became and `converted.losses` name the lines of your text that did not carry over; diagnostics then refer to `converted.dsl`.
- `analyze_codebase`: Walk a directory on disk and report detected cloud platform, services, top-level structure, and language breakdown. No network access — pure local filesystem scan. Useful to seed an architecture diagram.
- `list_starter_templates`: List built-in OpenFlow starter templates that can be loaded without any AI call. Returns names, titles, categories, and one-line summaries.
- `get_starter_template`: Return the OpenFlow DSL for a named starter template. Use list_starter_templates to discover available names.
- `list_diagram_node_types`: Quick reference for the OpenFlow DSL vocabulary: family names, shape words, edge arrows, and the wireframe controls and screen frames. Call get_syntax for the full grammar.
- `server_info`: Return the server version and the tools, resources and prompts it serves. Useful when debugging client connections.
- `discover_architecture`: Walk a local repo (compose, Dockerfiles, k8s, terraform, package manifests, datastore and HTTP-client usage) and return a proposed OFK C4 workspace as DSL, with evidence per unit. Deterministic, offline; review the proposal before committing it.
- `drift_report`: Compare an architecture model (inline dsl, a documentId, or else architecture.ofk in path) against a repository. Returns missing (in repo, not in model), undrawn (in model, no repo evidence) and changed (name matches, tech or dir differs) with evidence lines.
- `explain_element`: Everything known about one element: the model entry, its relations, repository evidence (when a path is given) and the ADR markdown files its links point at.
- `openflow_create`: Create an empty file-mode document in this process.
- `openflow_open`: Load a canonical document from disk into file mode and return its id.
- `openflow_save`: Write a document to disk (svg: true also writes the first page as a .svg beside it). With a paired editor and no documentId, saves what the editor currently shows.
- `whoami`: Local-only status: whether an editor is paired, and the documents this server holds.
- `create_diagram`: Draw a new diagram frame from text, placed right of what the page already holds (or at `at`). One undo step. To change a diagram that exists, use update_diagram with its frameId instead of drawing another.
- `update_diagram`: Redraw an existing diagram frame from new text, in place: same frame id and position, one undo step (a C4 workspace redraws every view page it owns). The text replaces the frame, as Generate in the code panel does, so canvas edits it does not carry (get_diagram lists them as `canvasEdits`) are dropped; `discarded` names any that were, each with its frameId.
- `get_diagram`: The DSL text of one diagram frame: what was authored while the canvas still matches it, else text regenerated from the canvas (`edited: true`). `canvasEdits` lists what was changed on the canvas against the authored text: recolours, moves, resizes, renames, icons, rewired or bent connectors, and shapes added or removed. Each has `carry`: attributes to merge into that node's existing `[ … ]` list (one list per node) to keep the edit, or null when the language cannot say it. `canvasEdits` is null, with `canvasEditsNote` saying why, when it could not be compared. `losses` names what the language cannot say at all. update_diagram drops anything the text you send does not carry.
- `list_diagrams`: Every diagram frame in the document: frameId, page, family, title, and `edited` (the canvas no longer matches its text).
- `get_syntax`: The OpenFlow DSL grammar: the full reference, or one family’s section.
- `search_icons`: Search the shipped icon packs by name (e.g. "lambda", "sql database"). Use the returned provider/slug in DSL `icon:` attributes.
- `find_icons_for`: Concept search ("cache", "queue", "auth") expanded into catalog queries and ranked; the fastest way to pick icon ids for architecture DSL.
- `move`: Move nodes on the canvas, by `delta`, or so the first id lands at `to` (the rest keep their offsets). Pass exactly one of the two. One undo step. A diagram regenerated from text lays its nodes out again.
- `style`: Set fill, stroke, stroke width, dash, opacity or text colour on nodes, or move the icon on icon cards (iconPlacement). Pass at least one property. One undo step. A diagram regenerated from text drops these unless its DSL carries them (get_diagram lists them as canvasEdits).
- `delete`: Delete nodes (with their children and the connectors attached to them) or connectors, by id. One undo step.
- `add_shape`: Add one shape without writing DSL (hand-layout only). Prefer create_diagram. Kinds: rectangle, ellipse, text, rounded, capsule, circle, diamond, triangle, trapezoid, parallelogram, hexagon, octagon, pentagon-tag, chevron, plus, star, heart, cloud, lightning, bookmark, speech-bubble, page, folder, list-card, filled-bar, half-round, cylinder, document, cube, prism, layer-stack, target, check-circle, cross-circle, numbered-circle, brace, bracket, pin, actor, arrow-up, arrow-down, arrow-left, arrow-right, venn, process, start, decision, end, custom, image, annotation, sticky, callout, pen, highlighter, line, arrow, architecture, provider_icon, group, section, swimlane, class, er_entity, mindmap, journey, sequence_participant, sequence_note, sequence_fragment, browser, mobile, chart, widget (wireframe control), frame (phone, browser… preset; drop widgets in with parentId).
- `export`: Export the document, a page, or a selection as SVG, PNG, PDF (print HTML), JSON, or an animation (animated SVG, GIF, MP4, WebM). Returns the file bodies. Raster animation needs a live editor (WebCodecs); a file host serves animated SVG only.
- `screenshot`: A PNG image of one diagram frame, or of the whole page, to check your work by eye. Needs a live editor (the user clicks "Connect agent").
- `fit_view`: Point the live editor's camera at one diagram frame, some ids, or (with neither) the whole page. Changes the view only, not the document.
- `get_document`: Nodes and connectors of one page, with ids, labels and geometry, plus `selection`: the ids the user has selected on that page in the live editor ("the box I selected"; empty in file mode or when nothing is selected). Use get_diagram for a diagram's DSL.
- `list_pages`: Every page in the document with its shape counts and diagram kind.

## FAQ

### Can an AI agent draw diagrams for me?

Yes, you can connect Claude Code, Cursor, or any MCP client to let the agent draw, restyle, and take screenshots of diagrams on a live canvas.

### How do I map a GitHub repository to a diagram?

You can type the owner/repo into the canvas box or use the CLI to map a local checkout to generate a map where every arrow is linked to specific lines of code.

### Can I use this with private GitHub repositories?

Yes, you can add a read-only GitHub token on the page or use the CLI to map a local checkout.
