Skip to main content
Glama

Mermaid MCP App

An MCP Apps server that gives Claude a render_mermaid tool: pass it raw Mermaid diagram source and it renders as an interactive SVG (pan/zoom, fit-to-width, copy source, fullscreen) directly inline in the conversation — instead of a static ```mermaid code block.

This is a standalone project. It owns all of its own dependencies (Mermaid, the MCP Apps SDK, etc.) and never touches any other project's package.json — it's meant to be a general-purpose tool available across every Claude Desktop conversation, not something wired into a specific codebase.

How it's wired up

Claude Desktop launches this as a local (stdio) MCP server via ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mermaid": {
      "command": "node",
      "args": ["/absolute/path/to/mermaid-mcp-app/dist/main.js"]
    }
  }
}

This is a global entry (not scoped to any one project), so render_mermaid is available in every Claude Desktop conversation, on every restart, with no further action needed — as long as dist/ has already been built (see below).

Required: Developer Mode

Claude Desktop only renders the full custom widget (toolbar, pan/zoom, copy button) when Developer Mode is enabled. Without it, only a reduced fallback (diagram only, no controls) shows up.

Enable once: Claude menu → Help → Troubleshooting → Enable Developer Mode. This is a persistent app setting — it should not need to be re-enabled after a restart, but if the toolbar/controls ever disappear, check this first.

Related MCP server: vizcharter

Project layout

File

Role

server.ts

MCP server: registers render_mermaid (+ its ui://mermaid/viewer-* UI resource), save_html_note, read_note / update_note, get_library_tree / organize_notes, list_agent_notes / delete_agent_note, and the app-only import / target-picker tools

renders.ts

On-disk store for each render (<id>.mmd / <id>.md + <id>.json sidecar)

bake.ts

Injects a render's state into the viewer HTML for the per-call page

mermaid-local.ts

Client for Mermaid Local's agent-api (list projects/folders, import a diagram, resolve / read / update any note, read the library tree and organize a project, list / delete the notes it saved)

note-source.ts

Reads note content for save_html_note / update_note from inline text or a local path, with size/shape checks

config.ts / configure.mjs

Persisted import target + agent-api URL, and the CLI that edits them

main.ts

Process entry point — stdio transport by default (what Claude Desktop uses), --http for local testing

mcp-app.html

View shell (the UI resource's HTML)

src/mcp-app.ts

View logic: connects to the host, renders Mermaid client-side, pan/zoom/copy/fullscreen/import

src/extract.ts

Reads source/type/id/title out of a live or replayed tool result

src/markdown.ts, src/content-type.ts

Markdown → HTML with ```mermaid fences held out as placeholders; the mermaid/markdown type

src/target-panel.ts, src/target-options.ts, src/targets.ts

The ▾ import-location picker (DOM, option building, shared types)

src/mcp-app.css

View styling (light/dark, follows host theme)

vite.config.ts

Bundles the View (Mermaid included) into a single self-contained dist/mcp-app.html

First-time setup / rebuilding after a fresh checkout

pnpm install
pnpm run build

dist/ is gitignored (it's a build artifact), so after cloning or git clean you must run pnpm run build before the mermaid entry in claude_desktop_config.json will work — it points directly at dist/main.js.

Diagrams and documents

render_mermaid takes a type:

  • mermaid (default): code is a Mermaid diagram, drawn with pan/zoom.

  • markdown: code is a Markdown document. Its ```mermaid fences are drawn inline, so a note can carry a few sentences of context next to the picture (a bare diagram is often too abstract to keep). Headings, lists, tables, code and links work; raw HTML is sanitized, links open through the host, and one bad diagram only breaks itself.

title is required for both. Importing sends the same type to Mermaid Local, so a document arrives as a Markdown note.

Importing into Mermaid Local

The viewer's → Mermaid Local button copies the diagram or document (named by its title) into the Mermaid Local notes app through its agent-api inbox. Mermaid Local must be running (pnpm dev / pnpm preview start the sync service) with a "local agent sync" folder chosen.

Where it lands is a project plus a folder path inside it (empty = project root), and it is remembered per workspace. render_mermaid takes a required workspace (the session's working directory, which the model fills in from its environment — Claude Desktop runs one server process for every session and its MCP roots are all sessions' workspaces mixed together, so the server can't tell them apart itself). The ▾ button next to the import button picks the target for the workspace that drew this diagram: two dropdowns, saved as soon as you change one, used for every later diagram from that workspace, and independent of every other workspace. A workspace you haven't picked for follows the shared default (LLM, project root, unless changed).

From a shell (run pnpm run build first):

node configure.mjs get
node configure.mjs set-target LLM "多模态与跨模态/对比学习"                      # shared default; omit the folder for the project root
node configure.mjs set-target 医联 会议 --workspace /Users/me/WORKSPACE/yi-lian   # one workspace
node configure.mjs set-url http://127.0.0.1:4789

The choices live in mermaid-local-config.json (git-ignored). A project or folder that doesn't exist yet is created on import. title is required by render_mermaid because it becomes the diagram's name in Mermaid Local.

Saving HTML pages

save_html_note files an HTML page — typically an interactive visualization Claude already published as an artifact — into Mermaid Local as an html note. It is deliberately not a render_mermaid type: it renders nothing, and its description tells the model to keep making visualizations through the host's own artifacts and to call this tool only when you ask to keep a page ("把这个可视化存到 Mermaid Local"). There is no button to click — the request is the decision — and the note lands at the same per-workspace import target as diagrams.

The page arrives one of two ways (exactly one per call):

  • path: absolute path of a local .html file, e.g. the file a Code-tab artifact was published from. Read as-is, and the model doesn't re-send the page.

  • html: the full document, inline. Needed for pages made in a chat, which exist only in the conversation; costs as many output tokens as the page is long.

Pages are capped at 4 MB (agent-api's body limit is 5 MB). Pages that load libraries from a CDN still need network access when opened in Mermaid Local. Requires a Mermaid Local whose inbox accepts html notes.

Editing, replacing and removing notes

Saving the same page twice makes two notes, and a "fix" that deletes the note and saves a new one throws away its id, URL, history and place in the folder tree. So notes can be changed in place:

  • save_html_note with replaces (a note id, or its Mermaid Local URL) puts the page into that existing HTML note instead of creating one — the shortest path when Claude regenerates a page it saved earlier.

  • read_note returns any note's source (by id or URL; saveTo writes it to a file instead of into the conversation) together with a baseHash, the fingerprint of that version.

  • update_note replaces a note's complete content (inline or from a file) and optionally renames it. With the baseHash from read_note it is refused if the note changed after it was read, and the model is told so — it must read again and redo the edit rather than overwrite what you typed meanwhile. Works on any note, not only ones the model saved. Mermaid Local keeps the previous version in the note's history, so one click rolls an edit back.

The edit is carried out by the open Mermaid Local page, and the tool waits for its answer (a few seconds), so an applied / refused result is real rather than assumed. If no page is open, the edit waits for the next time one is.

Organizing a project

get_library_tree shows how the library is laid out — each project as an outline of folders (with their full paths) and notes (type, title, short id), in the order the app displays them. organize_notes then changes it, for one project per call: create / rename / move folders, move notes into folders, and reorder items within a folder. The steps go in as one batch that is checked as a whole — if any step is invalid nothing is changed and the model is told which step and why — and the open Mermaid Local page carries it out (and the sidebar updates live).

Deliberately not possible: deleting folders or notes (the app does not yet sync folder deletions to the cloud, so a deleted folder would come back), moving notes to another project, and changing a note's content (that is update_note). The tool description tells the model to explain its plan to you before a big restructuring.

list_agent_notes and delete_agent_note remain for finding and removing notes. Deletion is scoped on purpose: Mermaid Local's agent-api keeps a ledger (agent-notes.json in the sync folder) of the notes written through it and refuses any other id, so the model can only delete notes it saved itself, never ones you wrote. A note that was still waiting to be imported is simply cancelled.

Requires an agent-api that returns note ids and supports PUT / resolve; restart pnpm dev / pnpm preview in Mermaid Local after updating it.

Making changes

There's no hot reload. After editing server.ts, main.ts, or anything under src/:

pnpm run build

Then force Claude Desktop to pick up the change — it does not notice on its own, even after the resource URI changes, because it appears to cache MCP UI resources somewhat aggressively:

  • Reliable: Developer menu → Reload MCP Configuration (this is what actually worked during development; simply killing the child process was not always sufficient)

  • Then test in a brand-new conversation — an already-open one may keep reusing its first-mounted widget instance and never re-fetch, regardless of server-side changes.

The ui://mermaid/viewer-<hash>.html resource URI is derived from a content hash of dist/mcp-app.html (see server.ts), so every rebuild is, in principle, a new resource the host can't confuse with a stale one — but "Reload MCP Configuration" is still the step that's actually been confirmed to work reliably.

Verifying changes without Claude Desktop

The official ext-apps repo ships a reference test host (examples/basic-host) that renders MCP Apps in a plain browser tab — much faster to iterate against than Claude Desktop itself:

# in this repo
pnpm exec tsx main.ts --http   # starts the server on :3901

# in a checkout of github.com/modelcontextprotocol/ext-apps
SERVERS='["http://localhost:3901/mcp"]' npx tsx examples/basic-host/serve.ts
# open http://localhost:8092 (sandbox iframe defaults to :8081, hardcoded by basic-host)

Design notes

  • securityLevel: "strict" in Mermaid's init config sanitizes diagram labels and disables click/script bindings — the diagram source is never executed as HTML/JS, even though it ultimately comes from the model.

  • Sizing: the SVG is sized directly (explicit pixel width/height on the <svg>), scaled by container width only and never above its natural size. Mermaid's default output is already a readable size, so small diagrams aren't stretched to fill a wide panel, and tall ones keep legible text instead of being squashed. The viewing box is sized to the diagram so the whole thing shows at once with no scrolling (the host grows the iframe to follow); a 4000px cap is only a safety valve, past which the box falls back to native overflow: auto scrolling. Zoom is ⌘/Ctrl + wheel or the toolbar buttons; drag-to-pan only activates once the diagram overflows the box (after zooming in), so at fit-size the mouse is left alone and node text stays selectable/copyable.

  • Why not CSS transform: scale() + overflow: hidden? That was the first implementation, and it visibly failed to clip inside Claude Desktop (computed styles said overflow: hidden / 640px, yet the diagram painted well past the box). Real layout sizes + native scroll avoid depending on that combination.

  • Two resize/re-render feedback loops had to be broken, both invisible in the ext-apps reference host and only reproducible in Claude Desktop: (1) a ResizeObserver on the viewport re-fitting on every resize, where the fit itself sets the viewport's height — now it only reacts to width changes, with a burst limit as a backstop; (2) re-rendering on every host-context-changed notification (the host sends many, all carrying theme) — now it only re-renders when the theme actually changes.

  • Debugging in Claude Desktop: the widget lives in a nested cross-origin iframe, so DevTools' frame picker is painful. Temporarily rendering computed styles/rects into the widget itself (a small log box outside the diagram container) was far faster than DevTools.

  • Clipboard: the sandboxed iframe blocks navigator.clipboard under Claude Desktop's permissions policy. The copy button falls back to document.execCommand("copy"), and if that also fails, to window.prompt() so there's always a way to get the source out manually.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for AI Diagram Maker — generate software engineering diagrams from natural language, code, ASCII diagram, images, or Mermaid. Inline diagram rendering using MCP apps UI and diagram URL in responses. Works with Cursor, Claude Desktop, Claude Code, and any MCP-compatible AI.
      5
      134 npm
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables Claude Code to create and edit presentation-grade visualizations such as cloud architecture diagrams, charts, KPI dashboards, and poster infographics, with auto-layout, themes, and export to SVG, PNG, JPG, and PDF.
      6
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to turn natural-language descriptions of systems, flows, and data into 25 types of hand-drawn Excalidraw diagrams with automatic layout and architecture-aware styling, then revise them conversationally and export to SVG or PNG. It can also persist a system as a version-controlled, queryable architecture knowledge graph, running fully offline without API keys.
      -