mcp-mermaid: an MCP server that renders Mermaid diagrams for AI agents

The gap mcp-mermaid fills between Mermaid text and a rendered image

Mermaid is a text-to-diagram syntax. An assistant that can write Mermaid can already produce a diagram description, but it cannot show the result without a renderer in the loop. mcp-mermaid is an MCP server that closes that loop: the model sends Mermaid source, the server returns a rendered artifact. The README frames the goal as generating "mermaid diagram and chart with AI MCP dynamically."

The audience is narrow and specific. It is for people running an MCP-capable client (Claude Desktop, VSCode, Cline, Cherry Studio, and similar) who want diagrams produced inside the conversation rather than pasted into a separate editor. The README also points at three adjacent projects: antvis/mcp-server-chart for charts, graphs and maps, antvis/Infographic for timeline, comparison, list and process figures, and a gallery at figure.ling.pub for browsing shared output. If your need is a chart rather than a diagram, the README itself sends you elsewhere.

One design decision is worth naming early. The server does not just return an image; it validates the Mermaid. The README says validation exists "to facilitate the model's multi-round output of correct syntax and graphics." That is the real value proposition. A rendering tool that fails silently is worse than no tool, because the model has no signal to correct itself.

How rendering actually happens: mermaid-isomorphic, Playwright and Chromium

The dependency list in package.json tells most of the story. Rendering is delegated to mermaid-isomorphic, which in turn needs a browser, and the project pulls in Playwright (^1.52.0) for that. The Dockerfile installs Chromium explicitly with npx playwright install --with-deps chromium, and package.json runs the same command as a postinstall hook.

That is the architecture in one sentence: an Express server (^5.1.0) speaks MCP over stdio, SSE or streamable HTTP, hands Mermaid source to mermaid-isomorphic, and serialises the result into one of several output forms. The MCP layer itself comes from @modelcontextprotocol/sdk (^1.27.1), with zod and zod-to-json-schema used to define and expose the tool schema.

The consequence for operators is that this is not a pure JavaScript renderer. Every install downloads a Chromium build, and every render spins up browser work. On a laptop that is invisible. In a container without the right system libraries, or on a CI runner with a tight image, it is the first thing that breaks. The project's own Dockerfile exists precisely because the naive npm install is not enough.

Transport choice is separate from rendering. The CLI defaults to stdio, which is what desktop clients use. SSE and streamable HTTP exist for the hosted and remote cases, and the README lists separate ports for each.

Installing mcp-mermaid and getting a first diagram out of Claude or Cline

The fastest path is the npx route the README gives for desktop apps. On macOS and Linux, the client config is a command plus two arguments. Add this to your MCP client's server configuration, then restart the client.

{
  "mcpServers": {
    "mcp-mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ]
    }
  }
}

On Windows the README wraps the same invocation in cmd, because npx is a shell script there:

{
  "mcpServers": {
    "mcp-mermaid": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-mermaid"
      ]
    }
  }
}

After restarting, the client should list a mcp-mermaid server with its tools available. Ask the model for a diagram, for example a flowchart of a login flow, and it should call the tool and return a rendered result. Expect the first call to be slow: the postinstall step runs playwright install --with-deps chromium, so the first npx invocation downloads a browser.

If you would rather run the server yourself, the README documents a global install and two transport modes. The SSE mode listens on port 3033 by default and the streamable mode on 1122.

npm install -g mcp-mermaid
mcp-mermaid -t sse
mcp-mermaid -t streamable

For a container, the README points at a published image rather than a local build:

docker pull susuperli/mcp-mermaid:latest
docker run -p 3033:3033 susuperli/mcp-mermaid:latest --transport sse
docker run -p 1122:1122 susuperli/mcp-mermaid:latest --transport streamable --port 1122

The access points are http://localhost:3033/sse for SSE and http://localhost:1122/mcp for streamable. The README notes that a global install also exposes http://localhost:3033/mcp, which is a small inconsistency in the documentation and worth checking against your actual process.

Output formats and where the mcp-mermaid trade-off bites

The README lists six output types: base64, svg, mermaid, file, svg_url and png_url. The split matters. base64, svg and mermaid keep everything local. file writes a PNG to disk, which the README describes as being for AI agents. The two URL modes go through public mermaid.ink links, which means the diagram content leaves your machine.

That last point is the limitation worth stating plainly. If you generate an architecture diagram of an internal system and ask for png_url, the Mermaid source is encoded into a request to a third-party service. The README presents URL modes as "remote-friendly" and does not discuss what that implies for confidential content. For internal infrastructure diagrams, stay on the local output types.

The second limitation is the browser dependency. Because rendering goes through Playwright and Chromium, the server is heavier than its TypeScript source suggests. A minimal container image, a locked-down network policy that blocks the Playwright download, or an ARM environment without matching browser builds are all cases where this server will not start cleanly. The README does not document a fallback renderer or an offline install path for Chromium.

The third is documentation depth. The README covers installation, CLI flags and output types, but it does not describe error behaviour when Mermaid source is invalid, does not document rollback or version pinning, and does not explain how validation failures are surfaced to the model. Those are exactly the details an operator needs when a diagram silently comes back wrong.

Docker, SSE and the self-hosted mcp-mermaid server case

Running mcp-mermaid as a shared HTTP service changes the deployment shape. Instead of each desktop client spawning its own npx process, one server listens on 3033 or 1122 and multiple clients connect. The README supports this directly, and the Dockerfile is built for it: a node:lts-bookworm-slim base, npm install --ignore-scripts followed by an explicit npm run build, then npx playwright install --with-deps chromium, then npm prune --omit=dev.

The --ignore-scripts flag in that Dockerfile is deliberate and worth understanding. It skips the postinstall hook from package.json, because the Dockerfile runs the Playwright install itself with the system dependencies included. If you write your own Dockerfile and keep the default postinstall, you get the browser install twice.

The entrypoint is node build/index.js with no default transport argument, so the container starts in stdio mode unless you pass --transport. The README's docker run examples always pass it. A container running stdio with no attached client will simply sit there, which is a common first-run confusion.

Self-hosting also raises the question of who can reach the port. The README does not document authentication or access control on the SSE and streamable endpoints. The cors dependency is present, but the README is silent on how it is configured. Treat the HTTP transports as something to put behind your own network boundary.

How mcp-mermaid compares with mcp-server-chart and a plain Mermaid CLI

The README itself names the closest alternative: antvis/mcp-server-chart, which it describes as generating "chart, graph, map." The difference is in the output language. mcp-server-chart targets statistical and geographic visualisations, the kind of thing you would otherwise reach for a charting library to produce. mcp-mermaid targets Mermaid, which is a diagram description language: flowcharts, sequence diagrams, state machines, entity relationships. If your agent is explaining a code path or a protocol handshake, Mermaid is the natural fit. If it is plotting a time series, it is not.

Against a plain Mermaid CLI in a build step, the difference is the feedback loop. A CLI renders a file you already wrote. mcp-mermaid sits inside the model's tool loop, so the model can write Mermaid, get a result back, and correct itself in the same turn. That is the whole reason to run a server rather than a script. The cost is that you now depend on a browser process, an MCP client that supports tools, and a server that stays up.

A third option the README gestures at is antvis/Infographic for timeline, comparison, list and process figures. Those are composition formats rather than diagrams, and choosing between them is a matter of what the model is trying to communicate, not which tool is better.

Maintenance, licence and what mcp-mermaid costs to keep running

The repository is not archived. The last push was on 2026-05-15, roughly four months before today. The most recent tagged release is 0.4.1 from 2026-02-12, following 0.4.0 in November 2025 and 0.3.0 in October 2025. That is a modest release cadence on a pre-1.0 package, and the version number is the honest signal: expect the tool schema and CLI surface to move.

The licence is MIT, stated in package.json and in the README as "MIT@hustcc". MIT is permissive and imposes no copyleft obligation on your own code. It does mean the project carries no warranty, and the README offers no support commitment. One licence-adjacent point that is not a legal question but a practical one: the dependency chain includes Playwright and Chromium, which have their own licence terms separate from this project's MIT grant. If you redistribute a container image, check those separately rather than assuming the MIT badge covers the whole stack.

The upgrade cost is dominated by the browser. Bumping mcp-mermaid means re-running the Playwright install in your image, and a Playwright major version can change which Chromium build is fetched. Pin the package version in your Dockerfile rather than tracking latest if you care about reproducible builds, since the README's Docker examples use susuperli/mcp-mermaid:latest.

Editorial conclusion

Adopt mcp-mermaid if your agent already writes Mermaid text and you want the rendered artifact back in the same turn, and if you can accept a Playwright Chromium download on install. Skip it if you only need a static Mermaid renderer in a build pipeline, or if your environment cannot run headless Chromium. Before rolling it out, verify that your MCP client supports the tool-call shape you plan to use, and check the outputType you want against the README's list, because the documentation does not describe what happens when rendering fails.

Frequently asked questions

Official sources

1. hustcc/mcp-mermaid on GitHub
2. License: MIT
3. Project website
4. README
5. Releases