Mermaid MCP App
Renders Mermaid diagram source as an interactive SVG inline in the conversation, with pan/zoom, fit-to-width, copy source, and fullscreen controls.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| MCP server: registers |
| On-disk store for each render ( |
| Injects a render's state into the viewer HTML for the per-call page |
| Client for Mermaid Local's |
| Reads note content for |
| Persisted import target + agent-api URL, and the CLI that edits them |
| Process entry point — stdio transport by default (what Claude Desktop uses), |
| View shell (the UI resource's HTML) |
| View logic: connects to the host, renders Mermaid client-side, pan/zoom/copy/fullscreen/import |
| Reads source/type/id/title out of a live or replayed tool result |
| Markdown → HTML with ```mermaid fences held out as placeholders; the |
| The ▾ import-location picker (DOM, option building, shared types) |
| View styling (light/dark, follows host theme) |
| Bundles the View (Mermaid included) into a single self-contained |
First-time setup / rebuilding after a fresh checkout
pnpm install
pnpm run builddist/ 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):codeis a Mermaid diagram, drawn with pan/zoom.markdown:codeis a Markdown document. Its```mermaidfences 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:4789The 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.htmlfile, 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_notewithreplaces(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_notereturns any note's source (by id or URL;saveTowrites it to a file instead of into the conversation) together with abaseHash, the fingerprint of that version.update_notereplaces a note's complete content (inline or from a file) and optionally renames it. With thebaseHashfromread_noteit 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 buildThen 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/heighton 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 nativeoverflow: autoscrolling. 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 saidoverflow: 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
ResizeObserveron 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 everyhost-context-changednotification (the host sends many, all carryingtheme) — 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.clipboardunder Claude Desktop's permissions policy. The copy button falls back todocument.execCommand("copy"), and if that also fails, towindow.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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Turn calls and notes into process flow diagrams in Claude, ChatGPT, VS Code, Cursor, and Teams.
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Let Claude, Cursor, or ChatGPT author Mermaid diagrams your team can read and share.
Draw architecture diagrams, UML, planning boards and clickable wireframes from your AI assistant.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP 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.5134 npm10MIT
- AlicenseAqualityDmaintenanceEnables 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.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude Desktop to draw and edit geometry constructions in the Eidograph desktop app via a local stdio-to-HTTP bridge.MIT
- FlicenseNot gradedqualityAmaintenanceEnables 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.-