Skip to main content
Glama

mermaid2svg

Convert mermaid markdown to svg as a web app, api and mcp server.

Handy for converting AI generated diagrams into SVG which can be inserted into FOR as an image.

Try it out on Huggingface spaces

Rendering is done in pure Python with mermaidx (no browser, Node.js or npm required):

import mermaidx
d = mermaidx.render(mermaid_code)
d.save("azure_architecture.svg")

Install

pip install -r requirements.txt      # or: pip install -e ".[all]"

Related MCP server: Vizdown-MCP

1. FastAPI REST web service

uvicorn mermaid2svg.api:app --host 0.0.0.0 --port 8000   # or: mermaid2svg-api

Interactive docs at http://localhost:8000/docs. All render endpoints return image/svg+xml (or HTTP 422 with a detail message for invalid Mermaid):

Method

Path

Body

GET

/health

–

POST

/render

JSON {"code": "graph TD; A-->B"}

POST

/render/text

raw text/plain Mermaid source

POST

/render/file

multipart upload, field name file

curl -X POST localhost:8000/render -H 'Content-Type: application/json' \
     -d '{"code": "graph TD; A-->B"}' -o diagram.svg
curl -X POST localhost:8000/render/text --data-binary @diagram.mmd -H 'Content-Type: text/plain' -o diagram.svg
curl -X POST localhost:8000/render/file -F file=@diagram.mmd -o diagram.svg

2. Gradio web app

python -m mermaid2svg.gradio_app      # or: mermaid2svg-gradio

Open http://localhost:7860, paste Mermaid source (or upload a .mmd/.mermaid/.txt/.md file), click Convert to SVG to preview the diagram and download the SVG.

3. MCP server

python -m mermaid2svg.mcp_server                                  # stdio (default)
python -m mermaid2svg.mcp_server --transport streamable-http --port 8000

Tools:

  • mermaid_to_svg(mermaid_code) – returns the SVG markup as a string.

  • save_mermaid_svg(mermaid_code, filename="diagram.svg") – writes the SVG to the output directory (MERMAID2SVG_OUTPUT_DIR, default ./output) and returns its path. The filename is sanitised so files cannot be written outside that directory.

Example client configuration (e.g. Claude Desktop / VS Code):

{
  "mcpServers": {
    "mermaid2svg": {
      "command": "python",
      "args": ["-m", "mermaid2svg.mcp_server"],
      "env": { "MERMAID2SVG_OUTPUT_DIR": "/path/to/output" }
    }
  }
}

Configuration

Variable

Default

Description

HOST / PORT

127.0.0.1 / 8000 (API), 7860 (Gradio)

Bind address

MERMAID2SVG_MAX_SOURCE_LENGTH

100000

Maximum Mermaid source length (chars)

MERMAID2SVG_OUTPUT_DIR

./output

Where the MCP save_mermaid_svg tool writes

Tests

pip install -e ".[test]"
pytest

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