mermAId MCP Server

MermAId Editor

A local Mermaid diagram editor designed for AI-assisted workflows. It's a pretty nice live Mermaid editor. But it's also a tool to be used with AI coding agents in generating plans. An AI coding agent (Claude Code, Codex, etc.) generates or updates diagrams via MCP or CLI, and you see the results rendered live in your browser. You can also edit diagrams directly — it's a full editor with syntax highlighting, linting, and vim keybindings. Push changes back to the agent, iterate, rinse and repeat.

The editor runs as a small Go server on localhost with a split-pane UI: a CodeMirror text editor on the left and a live Mermaid preview on the right.

<p> <img src="images/editor-ui-light.png" alt="Split-pane editor in light mode with code on the left and rendered diagram on the right" width="49%" /> <img src="images/editor-ui-dark.png" alt="Split-pane editor in dark mode with code on the left and rendered diagram on the right" width="49%" /> </p>

AI agents interact with the editor via MCP or CLI to generate and update diagrams programmatically.

!Claude Code interacting with the Mermaid editor

The native macOS app bundle is a self-contained executable that lives in the Dock and is freestanding (including the MCP server).

Features

• AI agent integration via MCP server or CLI tool — agents can get and set diagrams programmatically
• Live preview with debounced rendering as you type
• Vim keybindings (via codemirror-vim)
• Mermaid syntax highlighting and linting
• Pan and zoom on the diagram preview
• Export diagrams as SVG or high-resolution PNG
• Collapsible editor pane
• Single-instance enforcement — re-running the binary focuses the existing session
• Cross-platform: runs on macOS, Linux, and Windows
• Builds as a native macOS .app bundle with a menu-bar icon (tray app)

Installation

Requirements

• Go 1.25+
• Node.js / npm
• macOS only: Xcode Command Line Tools (for CGO — the native app window uses Cocoa/WebKit)

Build from source (macOS / Linux)

git clone https://github.com/kmatthias/mermaid-editor.git
cd mermaid-editor
make build

This installs JS dependencies, bundles the frontend, and compiles the Go binary. The resulting binary is ./mermaid-editor — static assets are embedded at compile time, so the single file is all you need.

On macOS, the build uses CGO to link against Cocoa and WebKit for the native app window. On Linux, no CGO or system libraries are required.

Build from source (Windows)

Windows requires Go and Node.js installed. If you have GNU Make (e.g. via Chocolatey, MSYS2, or Git Bash):

make build

Without Make, run the steps manually in PowerShell:

npm install
npx esbuild frontend/app.js --bundle --format=iife --minify --sourcemap --outfile=static/bundle.js
copy frontend\style.css static\style.css
go build -o mermaid-editor.exe .

Install to PATH

# macOS / Linux: copy the binary somewhere on your PATH
cp mermaid-editor /usr/local/bin/

# Or use go install on any platform (requires GOBIN on PATH)
go install .

On Windows, copy mermaid-editor.exe to a directory on your %PATH%, or use go install ..

Usage

# Run the editor (opens in your default browser)
./mermaid-editor

# Run in development mode with live JS rebuilds
make dev

The editor opens automatically in your default browser. If an instance is already running, it focuses the existing window instead of starting a new one.

Platform notes

| | macOS | Linux | Windows | |---|---|---|---| | Browser | Opens via open | Opens via xdg-open | Opens via rundll32 | | Native window | Yes (Cocoa/WebKit app) | No — browser only | No — browser only | | App bundle | make macapp | N/A | N/A | | CGO required | Yes (for native window) | No | No |

macOS App Bundle

make macapp

Creates MermAId Editor.app, a self-contained macOS application that lives in the menu bar. This target is macOS-only.

AI Agent Integration (Claude Code, etc.)

There are two ways to connect an AI agent to the editor. Pick whichever fits your workflow — both provide the same get/set diagram capabilities.

| | MCP Server | CLI Tool | |---|---|---| | How it works | Editor runs as an MCP server over stdio; the agent talks to it natively | A Ruby script calls the editor's HTTP API | | Agent discovers tools | Automatically (via MCP protocol) | Via instructions you add to CLAUDE.md | | Requirements | Just the binary | Ruby, plus a running editor instance | | Best for | Dedicated agent sessions | When you're already using the editor interactively |

---

Option A: MCP Server

The editor can run as an MCP server. In this mode it starts the HTTP server for the browser UI and exposes get_diagram / set_diagram tools over stdio. The agent discovers the tools automatically — no CLAUDE.md instructions needed.

Setup

Add the server to your Claude Code MCP config (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "mermaid-editor": {
      "command": "/path/to/mermaid-editor",
      "args": ["--mcp"]
    }
  }
}

That's it. Claude Code will start the editor when it needs it, and the MCP tools will be available automatically.

Tools

| Tool | Description | |------|-------------| | get_diagram | Returns the current diagram text and version | | set_diagram | Replaces the entire diagram (appears live in the browser) |

---

Option B: CLI Tool

The editor ships with bin/mermaid-cli, a Ruby script that talks to a running editor instance over its HTTP API. You start the editor yourself and tell the agent about the CLI via CLAUDE.md.

Setup

1. Start the editor normally:

   ./mermaid-editor

1. Add the CLI to your CLAUDE.md (project or global) so the agent knows how to use it:

   ## Mermaid Diagrams

   A mermaid editor is running locally. Use `bin/mermaid-cli` to interact with it:

   - `bin/mermaid-cli get` — print the current diagram to stdout
   - `bin/mermaid-cli set --text "graph TD; A-->B"` — set the diagram from a string
   - `bin/mermaid-cli set diagram.mmd` — set the diagram from a file
   - `bin/mermaid-cli status` — check if the editor is running
   - For multiline diagrams, avoid literal `\n` in plain quotes. Use ANSI-C quoting or a file/heredoc so real newlines are passed, e.g. `bin/mermaid-cli set --text $'sequenceDiagram\n  A->>B: Hi'` or `cat <<'EOF' > /tmp/diagram.mmd` then `bin/mermaid-cli set /tmp/diagram.mmd`

How it works

The CLI discovers the running editor automatically via its state files and talks to it over its localhost HTTP API. Changes made via set appear instantly in the browser preview.

Commands

| Command | Description | |---------|-------------| | mermaid-cli get | Print the current diagram text to stdout | | mermaid-cli set <file> | Replace the diagram from a file (- for stdin) | | mermaid-cli set --text "…" | Replace the diagram from a string | | mermaid-cli status | Check if the editor is running | | mermaid-cli help | Show usage information |

Other Make Targets

| Target | Description | |--------------|--------------------------------| | make help | Show all available targets | | make test | Run the test suite | | make stop | Stop a running instance | | make clean | Remove build artifacts |

Copyright 2026 Quantum Hug, Inc.