mcp-mermaid: turning Mermaid syntax into an MCP tool for AI clients
❤️ Generate mermaid diagram and chart with AI MCP dynamically.
At a glance
- What is it?
- hustcc/mcp-mermaid is a TypeScript MCP server that exposes Mermaid diagram rendering as a tool an AI client can call. It is useful when you want diagrams generated inside a chat session, and awkward when you already have deterministic diagram generation in CI.
- Who is it for?
- Adopt mcp-mermaid if you are already running an MCP-capable desktop client such as Claude, VSCode, Cline or Cherry Studio and want the model to emit Mermaid it can render without leaving the conversation. Do not adopt it if your diagrams are generated by a scripted pipeline, since the server adds an LLM in the loop where a fixed template would do.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 123 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap mcp-mermaid fills between an AI client and Mermaid
Mermaid is a text-to-diagram language. An AI client can write Mermaid source easily, but it cannot display that source as an image on its own. mcp-mermaid closes that gap by registering as a Model Context Protocol server, so the client gets a callable tool instead of a code block the user has to paste into a renderer. The README frames the project as generating Mermaid diagrams and charts 'with AI MCP dynamically', and the audience is anyone running an MCP-aware desktop app: Claude, VSCode, Cline, Cherry Studio and similar clients are named explicitly. If you have never configured an MCP server, this project is not the place to start, because the setup assumes you know where your client keeps its server list.
What the server actually does with a Mermaid string
The mechanism is narrow and worth stating plainly: the client sends Mermaid source, the server renders it, and the result comes back in one of several shapes. The README lists base64, svg, mermaid, file, svg_url and png_url as supported export formats. Two of those matter more than the rest. outputType file saves a PNG to disk, which the README describes as intended for AI agents. The URL modes produce public mermaid.ink links, which the README describes as remote-friendly. The project also claims validation of Mermaid input, and the stated purpose of that validation is to help the model converge on correct syntax across multiple rounds. That is the interesting design choice here: the server is built on the assumption that the first Mermaid string a model produces may not parse, and that a round trip is cheaper than a failed render. Style configuration is exposed too, with backgroundColor and theme named as supported keys, so the model can set them rather than hardcoding a look.
Installing mcp-mermaid in a desktop MCP client
For a desktop app, the README gives a JSON block to paste into the client's MCP server config. On macOS the command is npx with args -y and mcp-mermaid. On Windows the command is cmd and the args array is /c, npx, -y, mcp-mermaid. That difference is not cosmetic; getting it wrong is a common reason a server silently fails to start on Windows. For a global install, the README shows npm install -g mcp-mermaid, then mcp-mermaid -t sse or mcp-mermaid -t streamable. Local development is git clone, npm install, npm run build, then npm run start:sse or npm run start:streamable. The CLI options documented under -h are --transport or -t with values stdio, sse or streamable, defaulting to stdio; --port or -p defaulting to 3033; and --endpoint or -e, which defaults to /sse for SSE and /mcp for streamable. Direct node invocations are also documented, for example node build/index.js --transport streamable --port 1122. A Docker path exists as well, with the image susuperli/mcp-mermaid:latest and run commands such as docker run -p 3033:3033 susuperli/mcp-mermaid:latest --transport sse.
The port and endpoint details that will bite you first
The README is not fully consistent about where things listen, and this is the part to read twice. The access points section lists SSE at http://localhost:3033/sse and streamable at http://localhost:1122/mcp. The global install section then says streamable is reachable at http://localhost:1122/mcp locally or http://localhost:3033/mcp when installed globally. Those two statements describe different ports for the same transport depending on install method, and the README does not explain why. The CLI default for --port is 3033 regardless of transport, so a streamable server started without an explicit port would land on 3033, not 1122. If you are pointing a client at a fixed URL, pass --port explicitly rather than relying on the documented defaults. The endpoint flag has the same shape of ambiguity: it defaults to /mcp for streamable, which means a client configured for /sse against a streamable server will not connect.
Where mcp-mermaid is the wrong tool
The server is a renderer wrapped in a protocol, not a diagram generator. If your diagrams come from a fixed schema, a CI job that writes .mmd files and calls the Mermaid CLI is more predictable, faster and easier to diff in review. mcp-mermaid puts a language model between the data and the diagram, which is exactly what you want for exploratory work in a chat window and exactly what you do not want for a release artifact that must be byte-identical across runs. The URL output modes deserve separate caution: the README describes them as public mermaid.ink links, so anything you render that way is handed to a third-party service. There is no mention of authentication, access control or a self-hosted rendering backend in the material provided, and I cannot confirm from the README whether the server can be configured to avoid the external service entirely. Treat the URL modes as unsuitable for internal architecture diagrams until you verify that yourself.
How it differs from mcp-server-chart
The README points at a sibling project, antvis/mcp-server-chart, and the distinction is in the output medium rather than the protocol. Both are MCP servers that a client can call, but mcp-server-chart targets charts, graphs and maps, while mcp-mermaid targets Mermaid's own diagram grammar. The practical difference is what the model has to produce. With mcp-mermaid the model writes Mermaid source, which means it can express flowcharts, sequence diagrams and the rest of the Mermaid syntax the README claims full support for. With a chart-oriented server the model produces a chart specification instead. If your output is a sequence diagram of a request path, mcp-mermaid is the closer fit. If it is a bar chart of monthly figures, it is not, and the README itself says so by listing mcp-server-chart as the tool for that case. The same README entry also points at antvis/Infographic for timeline, comparison, list and process layouts, which is a third option for content that is structured but not a diagram in the Mermaid sense.
Version history, licence and the cost of staying current
The repository is MIT licensed, attributed to hustcc in the README. MIT is permissive, so bundling the server into an internal toolchain does not by itself create distribution obligations, but this is a description of the licence text and not legal advice; check the LICENSE file and your own policy. On maintenance, the release history shows 0.4.1 in February 2026, 0.4.0 in November 2025 and 0.3.0 in October 2025, with the last push to the default branch in May 2026. That is a steady cadence rather than a burst, and the version numbers are still in the 0.x range, which is a reasonable signal that the tool surface may still change. The upgrade cost is low if you pin a version in your MCP config, because the client starts the server on demand through npx. It is higher if you use the Docker image with the latest tag, since that tag moves. The README lists susuperli/mcp-mermaid:latest as the stable tag and points at Docker Hub for the full tag list, so a pinned digest is available if you want reproducible startup.
Editorial conclusion
Adopt mcp-mermaid if you are already running an MCP-capable desktop client such as Claude, VSCode, Cline or Cherry Studio and want the model to emit Mermaid it can render without leaving the conversation. Do not adopt it if your diagrams are generated by a scripted pipeline, since the server adds an LLM in the loop where a fixed template would do. Before wiring it in, verify three things: that your client actually supports the stdio config shape shown in the README, whether you need outputType file or one of the URL modes rather than base64, and which port your transport choice binds, because the README lists 3033 for SSE and 1122 for streamable, and the global install example also mentions http://localhost:3033/mcp.
Community notes