AI Integration (MCP Server)

Diagrammix includes a built-in MCP (Model Context Protocol) server that lets AI assistants like Claude and Codex read and modify your diagrams directly. Describe what you need in plain language, and the AI places symbols, connectors, and layouts on the canvas for you.

What Can AI Do?

  • Create diagrams from a description — ask for a flowchart, network topology, or org chart and get it on canvas instantly
  • Build mind maps — describe a topic and get a structured mind map
  • Read your document — AI sees your current shapes, connectors, layers, and styles
  • Modify existing elements — update text, colors, positions, or connector routing
  • Batch operations — create entire diagrams with symbols and connectors in a single step
  • Auto-layout and alignment — organize elements with natural language commands
  • Replicate a look from an image — hand the AI a reference picture and it builds a matching custom template and style
  • Export — generate SVG output on demand

Requirements

  • Diagrammix PRO (one-time purchase)
  • Diagrammix must be running with the MCP server enabled
  • At least one diagram document must be open
  • AI client and Diagrammix must be on the same machine (localhost)

No Node.js, npx, or mcp-remote is needed — Diagrammix bundles a native helper for clients that require it.

Setup

1. Enable the MCP Server

  1. Open Diagrammix
  2. Go to Diagrammix > Settings (or press Cmd+,)
  3. Switch to the AI Integration tab
  4. Toggle Enable AI Integration (MCP Server) on

The server starts on http://localhost:8420/mcp.

2. Configure Claude Desktop

Claude Desktop connects over stdio. Diagrammix ships a native stdio helper inside the app bundle, so no Node.js, npx, or mcp-remote is required.

  1. Click Copy Config in Diagrammix Settings — this fills in the exact path to the bundled helper for your installation
  2. Open the Claude Desktop config file: ~/Library/Application Support/Claude/claude_desktop_config.json
  3. Paste the config. It looks like this — the command path points to the helper inside wherever Diagrammix.app is installed:
{
  "mcpServers": {
    "diagrammix": {
      "command": "/Applications/Diagrammix.app/Contents/MacOS/diagrammix-mcp-stdio",
      "args": ["--url", "http://localhost:8420/mcp"]
    }
  }
}

Note: Use Copy Config rather than typing the path by hand — it points to the helper inside your actual app bundle, which Diagrammix keeps signed and up to date.

  1. Restart Claude Desktop. Diagrammix tools will appear in the chat.

3. Configure Claude Code (CLI)

Add to your project's .mcp.json or globally in ~/.claude/mcp.json:

{
  "mcpServers": {
    "diagrammix": {
      "type": "url",
      "url": "http://localhost:8420/mcp"
    }
  }
}

Claude Code supports Streamable HTTP natively — no bridge needed.

4. Configure Codex

Codex (app, CLI, and IDE extension share one MCP configuration) connects over Streamable HTTP. Configure it either way:

Option A — config.toml. Click Copy Config in the Codex section of Diagrammix Settings and paste into ~/.codex/config.toml:

[mcp_servers.diagrammix]
url = "http://localhost:8420/mcp"
enabled = true
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 60

Option B — CLI. Click Copy Command in Diagrammix Settings, or run:

codex mcp add diagrammix --url http://localhost:8420/mcp

5. Other MCP Clients

Any MCP-compatible client can connect using:

  • Transport: Streamable HTTP
  • Endpoint: http://localhost:8420/mcp
  • Protocol: JSON-RPC 2.0 over HTTP POST

Note: ChatGPT Desktop requires HTTPS and does not support localhost connections directly.

Usage Examples

Create a Flowchart

"Create a flowchart with Start, Decision, Process A, Process B, and End. Connect Start to Decision, Decision to Process A (Yes) and Process B (No), and both processes to End."

The AI will use batch_create to place all symbols and connectors in a single undo step.

Modify Existing Diagram

"Change the fill color of all rectangles to blue and make the text bold."

The AI reads your elements with get_elements, then updates each one with update_element.

Auto-Layout

"Apply top-to-bottom layout with 60px spacing between rows."

The AI calls apply_layout with your preferred direction and spacing.

Replicate a Look from an Image

"Here's a screenshot of our brand's diagram style. Recreate these shapes and colors as a custom template and style I can reuse."

Give the assistant a reference image and it can generate matching SVG shapes and arrowheads, assemble them into a custom template, and define a matching custom style. It uses tools such as create_custom_template, add_custom_shape, add_custom_arrowhead, and create_style, so the result is a reusable pack — not a one-off drawing.

Tips

  • Start with a description — the more specific you are, the better the result
  • Iterate — ask AI to adjust colors, labels, or layout after the initial creation
  • Undo freely — all AI changes support Cmd+Z undo
  • Use notation symbols — ask the AI to use specific notation packs for consistent styling
  • Batch is better — for new diagrams, AI creates everything in one step so undo reverts the whole thing