Skip to main content
Glama
dgmo-mcp
by diagrammo
README.md
# @diagrammo/dgmo-mcp

**Turn a conversation into a real diagram — without leaving your AI tool.**

[![npm version](https://img.shields.io/npm/v/@diagrammo/dgmo-mcp.svg)](https://www.npmjs.com/package/@diagrammo/dgmo-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@diagrammo/dgmo-mcp.svg)](https://www.npmjs.com/package/@diagrammo/dgmo-mcp)
[![license](https://img.shields.io/npm/l/@diagrammo/dgmo-mcp.svg)](./LICENSE)

This MCP server gives Claude (and any MCP-compatible AI tool) the ability to render
**sequence diagrams, flowcharts, ER diagrams, C4 architecture, gantt charts, and 40+
other chart types** from concise text markup — then hand the result off to a full
editor for refinement. Ask for a diagram in chat; get a real one back.

<table>
  <tr>
    <td width="50%"><img src="https://raw.githubusercontent.com/diagrammo/dgmo-mcp/main/assets/sequence.png" alt="Sequence diagram" /></td>
    <td width="50%"><img src="https://raw.githubusercontent.com/diagrammo/dgmo-mcp/main/assets/c4.png" alt="C4 architecture diagram" /></td>
  </tr>
  <tr>
    <td width="50%"><img src="https://raw.githubusercontent.com/diagrammo/dgmo-mcp/main/assets/gantt.png" alt="Gantt chart" /></td>
    <td width="50%"><img src="https://raw.githubusercontent.com/diagrammo/dgmo-mcp/main/assets/flowchart.png" alt="Flowchart" /></td>
  </tr>
</table>

## What you can do

Ask in plain language — _"diagram the auth flow as a sequence"_, _"chart the Q3 plan as
a gantt"_, _"draw our services as a C4 diagram"_ — and Claude writes the markup and
renders it. The markup stays readable and diffable:

```
flowchart Mutiny Resolution
direction-tb

[Sail]     Set sail under the captain
{Trouble?} Discontent in the crew?
{Vote}     Crew vote called
[Mutiny]   Seize the ship

(Sail) -> (Trouble?)
(Trouble?) -Yes-> (Vote)
(Vote) -Mutiny-> (Mutiny)
```

→ renders to the flowchart above. All rendering happens **locally** — no diagram data
leaves your machine.

## Tools

| Tool                     | What it does                                                                | Over HTTP |
| ------------------------ | --------------------------------------------------------------------------- | --------- |
| `render_diagram`         | Render DGMO markup to **SVG or PNG**                                        | yes       |
| `validate_diagram`       | Check markup and report parse errors, without rendering                     | yes       |
| `suggest_chart_type`     | Suggest the chart types that fit a description                              | yes       |
| `list_chart_types`       | List all supported chart types, marking the beta ones                       | yes       |
| `get_language_reference` | Get DGMO syntax documentation for accurate generation                       | yes       |
| `get_examples`           | Fetch worked examples for a chart type                                      | yes       |
| **`share_diagram`**      | Get a shareable **diagrammo.app** URL — hand your diagram to the web editor | yes       |
| **`open_in_app`**        | Open the diagram **straight into the Diagrammo desktop app** for editing    | no        |
| `check_app_installed`    | Report whether the desktop app is installed                                 | no        |
| `preview_diagram`        | Render one or more diagrams and open an **HTML preview** in the browser     | no        |
| `generate_report`        | Build a polished **multi-section HTML report** with ToC and optional source | no        |
| `put_space_diagram`      | Write a diagram into a **Diagrammo Cloud space**, by folder and title       | yes       |
| `get_space_diagram`      | Read a diagram from a Cloud space, by id or by folder and title             | yes       |
| `list_space_diagrams`    | List every diagram in a Cloud space                                         | yes       |

The three space tools send the diagram to Diagrammo Cloud. They need a space API key
(minted on the Diagrammo account page) as `DGMO_API_KEY` in the server's environment —
never as a tool argument, so the key stays out of the transcript.

`share_diagram` and `open_in_app` are the bridge out of chat: a diagram Claude generates
becomes something you can refine, restyle, and embed — see below.

The four marked **no** open a browser or launch the desktop app. Over HTTP that would
happen on the machine running the server rather than on yours, so they are not offered
there — see [Serving over HTTP](#serving-over-http).

## Beyond the MCP server

The MCP server is one entry point into **[Diagrammo](https://diagrammo.app)** — a whole
ecosystem built on the same DGMO markup. Generate in chat, refine in a real editor,
embed anywhere:

- **[diagrammo.app](https://diagrammo.app)** — the desktop app. `open_in_app` drops an
  AI-generated diagram straight into it, with live preview, palettes, and export.
- **[online.diagrammo.app](https://online.diagrammo.app)** — a full editor in the
  browser, zero install. `share_diagram` URLs open right here.
- **Docs integrations** — drop DGMO fenced code blocks into your docs site:
  [remark-dgmo](https://www.npmjs.com/package/remark-dgmo),
  [astro-dgmo](https://www.npmjs.com/package/astro-dgmo),
  [docusaurus-plugin-dgmo](https://www.npmjs.com/package/docusaurus-plugin-dgmo),
  [fumadocs-dgmo](https://www.npmjs.com/package/fumadocs-dgmo).
- **Obsidian** — the _Diagrammo Diagrams_ community plugin renders DGMO in your vault.
- **CLI** — `npx @diagrammo/dgmo-cli file.dgmo -o out.png`, or install it with `npm install -g @diagrammo/dgmo-cli` (macOS and Linux).

> **One markup, everywhere.** A diagram you generate here renders identically in the
> app, in your docs, and in Obsidian — because they all speak DGMO.

**[→ Try it free at diagrammo.app](https://diagrammo.app)**

## Setup

### Easiest — one command

Install the [`dgmo`](https://www.npmjs.com/package/@diagrammo/dgmo-cli) CLI and let it wire everything up:

```bash
npm install -g @diagrammo/dgmo-cli   # macOS and Linux
dgmo install                         # auto-detects Claude Code, Codex, Claude Desktop, Cursor, …
```

Prefer Homebrew or pacman? See [diagrammo.app/dev](https://diagrammo.app/dev#cli).

`dgmo install` configures each detected assistant non-interactively and points it at `dgmo mcp`, so there's no separate package to install or prompts to answer. Target one surface with `dgmo install claude-code` (or `codex`, `claude-desktop`, …).

### Manual configuration

Prefer to edit configs yourself? Point any MCP client at the server via `npx` (no global install needed):

**Claude Code** — `.claude/settings.local.json`; **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "dgmo": {
      "command": "npx",
      "args": ["-y", "@diagrammo/dgmo-mcp"]
    }
  }
}
```

If you have the `dgmo` CLI installed, `{ "command": "dgmo", "args": ["mcp"] }` works too. Restart the client after saving — the tools appear automatically.

### Serving over HTTP

The setups above launch the server as a child process and talk to it over its standard
input and output. That needs the server and the client on the same machine. Where they
are not — a hosted agent platform, a container, one server shared by several people —
start it as an HTTP endpoint instead. The same endpoint also suits one machine, when you
want a single server always running for every AI tool you use:

```bash
dgmo mcp --http                              # with the dgmo CLI installed
npx -y @diagrammo/dgmo-mcp --http            # http://127.0.0.1:3333/mcp
MCP_TRANSPORT=http MCP_PORT=8080 npx -y @diagrammo/dgmo-mcp
```

Every option takes a flag or an environment variable, whichever your setup can express:

| Flag                 | Variable              | Default     | What                                       |
| -------------------- | --------------------- | ----------- | ------------------------------------------ |
| `--http`             | `MCP_TRANSPORT=http`  | off         | Serve streamable HTTP instead of stdio     |
| `--port <n>`         | `MCP_PORT`            | `3333`      | Port to listen on                          |
| `--host <addr>`      | `MCP_HOST`            | `127.0.0.1` | Interface to bind                          |
| `--path <path>`      | `MCP_PATH`            | `/mcp`      | Path the endpoint answers on               |
| `--allow-host <h>`   | `MCP_ALLOWED_HOSTS`   | loopback    | Extra `Host` headers to accept, repeatable |
| `--allow-origin <o>` | `MCP_ALLOWED_ORIGINS` | own origin  | `Origin` headers to accept, repeatable     |

Each request is served independently — no sessions, nothing kept between calls — so one
endpoint can serve several clients at once.

> **The server has no authentication of its own.** It binds loopback by default and
> rejects requests carrying a `Host` header it was not told to expect, or an `Origin`
> header other than its own unless `--allow-origin` names it, which is enough
> for a client on the same machine or inside the same container. Anything reachable from
> a wider network needs your own authentication in front of it, and `--allow-host` for
> the hostname it will be reached by. Binding a non-loopback interface without naming a
> host prints a warning saying so.

`--help` prints all of this from the installed version.

#### Keep it running

Run the server as a background service so it starts at login and restarts if it stops.
Change the `dgmo` path to what `which dgmo` prints.

**Linux — systemd user service**, saved as `~/.config/systemd/user/dgmo-mcp.service`:

```ini
[Unit]
Description=Diagrammo MCP server over HTTP
After=network.target

[Service]
ExecStart=%h/.local/bin/dgmo mcp --http
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target
```

```bash
systemctl --user daemon-reload
systemctl --user enable --now dgmo-mcp
```

**macOS — launchd agent**, saved as `~/Library/LaunchAgents/app.diagrammo.mcp.plist`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>app.diagrammo.mcp</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/dgmo</string><string>mcp</string><string>--http</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict><key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string></dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>
```

```bash
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/app.diagrammo.mcp.plist
```

Then point each AI tool at `http://127.0.0.1:3333/mcp` as a streamable-HTTP MCP server.

## Privacy

All rendering is **local**. Your diagram markup and the images it produces never leave
your machine, except when you explicitly call `share_diagram` (which encodes the diagram
into a diagrammo.app URL). See the [privacy terms](https://diagrammo.app/terms#mcp-privacy).

## Dev hub (AI-tuning tools)

```bash
pnpm hub
```

One command, one server, one browser tab. The hub opens a tabbed shell over the
three AI-tuning dev tools — switch between them with the top tabs, no separate
ports or commands to remember:

- **Trigger tuning** — edit the phrase/concept vocabulary that drives
  `suggest_chart_type`, score prompts live, save back to `triggers.json`.
- **LLM judge** — judge chart-type descriptions against prompts with `claude -p`.
- **Guidance studio** — author the per-type **styling guidance** the server
  delivers (the `<!-- TIPS -->` blocks in dgmo's `language-reference.md`, sliced
  into `get_language_reference`): pick a type, edit how the AI is told to style
  it, run a prompt against a committed dataset fixture (so inputs never move
  between runs), and see the generated DGMO + rendered image side by side. The
  picker doubles as a coverage bar; "Compare 3×" renders no-guidance vs your
  tips for a by-eye check; Save validates and writes back to
  `language-reference.md`.

These tools are dev-only and never bundled into the published server. (The
standalone `pnpm harness` and `pnpm studio` scripts still run a single tool each
if you ever want one in isolation.)

## Contributing & releases

Development setup and the release workflow live in [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT

TDQS

A4/5.0

Scored across 14 tools

Disambiguation4/5

Most tools target clearly distinct purposes: language lookup (get_language_reference, list_chart_types, get_examples), authoring aids (suggest_chart_type, validate_diagram), output routes (render_diagram, preview_diagram, open_in_app, share_diagram), and cloud storage (put/get/list_space_diagram). The four output-route tools overlap conceptually, but the descriptions clearly delineate SVG/PNG text, browser HTML preview, desktop app, and shareable URL, and check_app_installed explicitly disambiguates open_in_app vs share_diagram. The reference-lookup tools are also carefully cross-referenced (suggest_chart_type appends the reference section, so get_language_reference is only needed on switch), leaving only minor residual ambiguity between render_diagram and preview_diagram.

Naming Consistency4/5

All names are snake_case, verb-first, and follow a verb_noun pattern (render_diagram, validate_diagram, share_diagram, list_space_diagrams, get_examples). Minor deviations appear in put_space_diagram and open_in_app, which use a prepositional qualifier rather than a plain noun, but both remain predictable within their sub-groups (cloud CRUD uses put/get/list).

Tool Count5/5

Fourteen tools is well within a healthy range and each one earns its place: authoring helpers, output routes, cloud CRUD, and reporting cover the domain without redundancy. The grouping into language/reference, render/output, and cloud storage is coherent and not padded.

Completeness4/5

The surface covers the full lifecycle of authoring (suggest, reference, examples, validate, render), delivery (preview, share, open, report), and cloud storage with put/get/list. The main gap is that the cloud space is read-write-list only — there is no delete or move/rename operation for space diagrams, and no folder-listing tool, which an agent managing a space would likely need.

Maintenance

ActivityActive
ResponsivenessLimited data