Allows creating Mermaid diagrams from structured JSON IR and rendering them to PNG or SVG using Mermaid CLI, with support for many Mermaid diagram types.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mermaid-mcp Turn this JSON IR into a flowchart and render it as PNG."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets agents build Mermaid diagrams from structured JSON IR instead of hand-writing Mermaid syntax, then renders them to PNG/SVG with Mermaid CLI 12 so the host app can show the result.
The IR layer is copied verbatim from
sohampatwardhan/mermaid-skill (render.py
and its schema docs), so the guardrails match the skill exactly. The skill does not need to
be installed. Same JSON in, same Mermaid out. Invalid IR fails closed: an unknown kind, a
missing field, or an edge to an undeclared node is an error, never a silent drop.
Tool | Input | Output |
|
| Mermaid source text |
| exactly one of | JSON text |
| optional | all families/targets, or the IR fields and example for one target |
Agent workflow: list_ir_targets → list_ir_targets(target=…) → render(ir=…). Use
from_ir alone when you only need the Mermaid text (e.g. to paste into Markdown).
render(source=…) validates and displays Mermaid you already have. It is not a way to skip
the IR when the content is structured.
render always renders to SVG first and rejects Mermaid's error-placeholder SVG, which
mermaid-cli sometimes writes while still exiting 0. On any failure the tool returns an error
with Mermaid's message (no JS stack trace) and the offending source.
There are 38 targets across graph (flowchart, mindmap, block, C4 ×5, architecture-beta,
erDiagram, classDiagram, swimlane-beta, agentflow-beta, wardley-beta), sequence
(sequenceDiagram, zenuml), state-machine, timeline (gantt, timeline), requirement-links,
chart (pie, xychart, sankey, quadrantChart, radar-beta, treemap-beta, venn-beta), packet,
board (kanban), journey, git, tree, cynefin, eventmodeling, grammar, usecase, and
info. Full schemas are in src/mermaid_mcp/reference/. Known gaps
per type are in coverage.md.
{
"diagram": "graph", "target": "flowchart", "direction": "LR",
"nodes": [
{ "id": "start", "label": "Request", "kind": "terminator" },
{ "id": "ok", "label": "Valid?", "kind": "decision" },
{ "id": "db", "label": "Orders", "kind": "store" }
],
"edges": [
{ "from": "start", "to": "ok" },
{ "from": "ok", "to": "db", "label": "yes" }
]
}from_ir returns:
flowchart LR
start@{ shape: stadium, label: "Request" }
ok@{ shape: diamond, label: "Valid?" }
db@{ shape: cyl, label: "Orders" }
start --> ok
ok -->|"yes"| dbChange "to": "db" to "to": "dbx" and the call fails with
invalid IR: graph/flowchart edge references undeclared node: {...}.
Related MCP server: diagrams-mcp
Python 3.10+
For render: Node 22.13+ and @mermaid-js/mermaid-cli@12.0.0. Mermaid 11 does not
register agentflow-beta or usecase-beta, and mermaid-cli 12 needs Node 22.
The server uses $MERMAID_MMDC if set, then mmdc on PATH, then
npx -y @mermaid-js/mermaid-cli@12.0.0. The npx fallback downloads the CLI and Chromium on
the first render, which can exceed a host's tool timeout. Install it once instead:
npm install -g @mermaid-js/mermaid-cli@12.0.0
mmdc --version # 12.0.0If mmdc on PATH is not 12.x, render still runs but adds a warning to its result.
from_ir and list_ir_targets need no Node at all.
This package is not on PyPI yet. Run it straight from GitHub with uv:
uvx --from git+https://github.com/sohampatwardhan/mermaid-mcp mermaid-mcp --versionOr install it into an environment:
pip install git+https://github.com/sohampatwardhan/mermaid-mcp
# or, from a clone:
pip install -e ".[test]"The server speaks MCP over stdio. The command is mermaid-mcp, or
uvx --from git+https://github.com/sohampatwardhan/mermaid-mcp mermaid-mcp without installing.
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"mermaid": {
"command": "uvx",
"args": ["--from", "git+https://github.com/sohampatwardhan/mermaid-mcp", "mermaid-mcp"]
}
}
}If you installed with pip, use "command": "mermaid-mcp" and drop args.
claude mcp add --scope user mermaid -- \
uvx --from git+https://github.com/sohampatwardhan/mermaid-mcp mermaid-mcp
claude mcp list # mermaid ... ConnectedUse the same command / args as the Cursor example in the host's MCP config (for Claude
Desktop, claude_desktop_config.json → mcpServers). Pass settings through the host's env
block:
"env": { "MERMAID_PUPPETEER_CONFIG": "/path/to/puppeteer.json" }Variable | Purpose |
| Mermaid CLI command to use, e.g. |
| npx fallback package (default |
| puppeteer JSON passed to |
| seconds per mmdc run (default 120) |
The same code paths are available without an MCP host, mirroring the skill's scripts:
mermaid-mcp from-ir diagram.json > diagram.mmd # like render.py ("-" reads stdin)
mermaid-mcp check diagram.mmd -o diagram.png # like check.sh (.png or .svg)
mermaid-mcp check -c 'flowchart TD; A-->B'
mermaid-mcp # run the MCP server on stdiocheck exits 0 on a clean render, 1 on a render failure or error SVG, 2 on bad input, and 3
when no Mermaid CLI is found.
Upstream files live unmodified in src/mermaid_mcp/vendor/render.py,
src/mermaid_mcp/reference/*.md, and tests/upstream/tests/test_render.py.
src/mermaid_mcp/vendor/UPSTREAM.json pins the upstream commit and each file's sha256.
tests/test_vendor.py fails if any of them is edited by hand.
python scripts/sync_upstream.py --check # does upstream main differ from the vendored copy?
python scripts/sync_upstream.py # pull main (or --ref <tag|branch|sha>) and re-pin
pytest # includes the upstream test suite, unmodifiedReview the diff, especially new targets. list_ir_targets picks up new serializers and
schema sections automatically. The Upstream drift workflow runs --check weekly.
pip install -e ".[test]"
npm install -g @mermaid-js/mermaid-cli@12.0.0
MERMAID_MCP_REQUIRE_RENDER=1 pytest -qThe suite covers:
IR: the wrapper matches upstream output byte for byte, and invalid IR fails closed. Every target resolves to a schema section.
Upstream parity: mermaid-skill's own test_render.py. Its check.sh calls go through a
shim into this package's renderer, so every upstream case is really rendered by mermaid-cli 12.
Renderer: real PNG/SVG output and Mermaid-12-only types (agentflow-beta). A real
mermaid-cli 12.0.0 exit-0 error SVG (wardley-beta with : in a label) is rejected, and
CLI resolution order is checked.
MCP: tool listing and calls over an in-memory client and over real stdio, including error results and image blocks.
Without a Mermaid CLI, tests that need a real render are skipped unless
MERMAID_MCP_REQUIRE_RENDER=1 is set. CI sets it, installs the pinned CLI on Node 22, and
tests Python 3.10 and 3.13.
MIT, same as mermaid-skill.
Convert diagram JSON IR to Mermaid source. Deterministic; fails on unknown kinds, missing fields, or undeclared ids. IR: {diagram, target, ...}; see list_ir_targets.
| Name | Required | Description | Default |
|---|---|---|---|
| ir | Yes | ||
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral detail: deterministic output and failure on unknown kinds, missing fields, or undeclared ids. This goes beyond the structured annotations and helps the agent predict failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core purpose in the first sentence. Every sentence adds value: purpose, determinism/failure behavior, and IR shape/target reference. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description covers purpose, failure behavior, and points to a sibling for targets. However, the target parameter is not clearly explained, and the IR format note is ambiguous about whether 'target' is a field in the IR object or the separate parameter. This leaves meaningful gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides some IR shape guidance ('IR: {diagram, target, ...}') and points to list_ir_targets, but it does not clearly explain the 'target' parameter's role or the string form of 'ir'. This is partial compensation, not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Convert diagram JSON IR to Mermaid source.' This clearly identifies what the tool does. However, it does not explicitly differentiate from the sibling tool 'render', so it stops short of full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context about when the tool applies (converting IR to Mermaid) and points to 'list_ir_targets' for target information. It does not explicitly state when to prefer this tool over 'render' or provide exclusion criteria, so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported IR targets, or pass target to get that target's IR fields and example.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already convey readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by disclosing the conditional behavior of the optional target parameter and what the caller gets in each mode: supported targets, or fields and an example for a specific target.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence covers both tool modes with no filler. The primary action is front-loaded, and the optional parameter behavior is appended naturally and economically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, one-optional-parameter tool, the description covers the two relevant call shapes and their expected outputs. It could mention error behavior for an invalid target, but the agent can list supported targets first, so no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema gives no description for the target parameter (0% coverage), but the description explains its semantic effect: omitting it lists all targets, while supplying it switches to detail mode for that target. It doesn't enumerate valid target values, but 'supported' implies they are discoverable from the list output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific action, 'List supported IR targets', and then clarifies an optional second mode: passing a target returns that target's IR fields and example. This clearly distinguishes it from the siblings from_ir and render, which are about conversion and rendering rather than target listing/inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear conditional guidance: call with no argument to list all targets, or pass a target to get its IR fields and example. It doesn't explicitly state when not to use it or compare it to from_ir/render, but the two usage modes are unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate and render a diagram with Mermaid CLI 12. Pass ir (preferred) or Mermaid source. Returns the Mermaid source plus PNG image (and SVG if requested). Fails on render errors.
| Name | Required | Description | Default |
|---|---|---|---|
| ir | No | ||
| theme | No | ||
| source | No | ||
| target | No | ||
| formats | No | ||
| save_dir | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description need not repeat those safety traits. It adds useful behavioral context: it 'Fails on render errors' and returns the Mermaid source plus PNG (and SVG if requested). Though it omits details about file saving via save_dir, the description does not contradict annotations and adds value beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence, front-loading the core action and input method. It avoids redundant words but could be structured to list parameters more clearly. It is concise enough to be quickly parsed, though not perfectly organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, no output schema, and no schema descriptions, the description is far from complete. It covers the input source and the return format, but misses the output formats configuration, save directory, theme selection, and any relationship to sibling tools. An agent would need to inspect the schema (which has no descriptions) or guess, making the tool hard to use correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but only explains two of the six parameters: 'ir' and 'source'. It does not address theme, target, formats, or save_dir, leaving the agent blind to their purpose and acceptable values. This is a significant gap for a tool with six parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb ('Validate and render') and the resource ('a diagram'), and specifies the Mermaid CLI 12. It distinguishes this tool from siblings like from_ir (likely converting IR to source) and list_ir_targets by focusing on the rendering step, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides guidance on input selection ('Pass ir (preferred) or Mermaid source'), implying when to use which form. However, it does not explicitly compare with sibling tools or state conditions when one should use this instead of alternatives. The context is clear enough for an agent to infer the right usage in most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0from_irlist_ir_targetsrenderScored across 3 tools
Each tool has a clearly distinct purpose: from_ir converts IR to Mermaid source, render produces images from source or IR, and list_ir_targets provides metadata about supported IR targets. There is no functional overlap that would cause an agent to misselect.
Tool names are all lowercase with underscores and generally readable. However, from_ir does not follow the verb-first pattern of render and list_ir_targets, creating a minor stylistic deviation that reduces full consistency.
At three tools, the server is tightly scoped to its stated IR-to-Mermaid rendering workflow. Each tool earns its place with a distinct responsibility, and the count is well within the typical 3-15 range.
The set covers the full pipeline: IR to source, source/IR to rendered image, and metadata lookup for IR targets. A slight gap is the absence of a source-to-IR conversion, but that is not implied by the server's purpose and can be worked around.
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
