uml-mcp

1. Demo

The recording comes from the repository (docs/assets/mcp-app-demo.mp4). One generate_uml_batch call returns four diagrams as tabs in the MCP App viewer; the user switches tabs, then re-renders one diagram in another format.

Clients without MCP Apps get the same result as an inline image plus links, which is what most chat clients show:

3. Overview

The server exposes five tools, plus resources (uml://types, uml://examples, uml://templates), prompts and skill files that teach the assistant each notation.

The README counts 46 diagram types: 37 rendered by Kroki and 9 by four bundled plugins (D3 force and cloud diagrams with real logos, stack diagrams, archify-style architecture, workflow and sequence diagrams, and 2D/3D LLM layer maps).

4. What happens on a tool call

generate_uml in mcp_core/tools/diagram_tools.py is a thin wrapper; the work is in generate_from_request (mcp_core/core/diagram_service.py) and run_diagram_pipeline (mcp_core/core/diagram_rendering.py).

sequenceDiagram
  participant AI as Assistant (MCP client)
  participant Tool as generate_uml
  participant Svc as generate_from_request
  participant Cache as Render cache
  participant Pipe as run_diagram_pipeline
  participant K as Kroki
  participant FB as PlantUML server / mermaid.ink
  AI->>Tool: diagram_type, code, output_format, theme, scale
  Tool->>Tool: resolve_diagram_type (exact key, else suggestions or a picker)
  Tool->>Svc: DiagramRequest
  Svc->>Svc: GenerateUMLInput validation, type in catalog?
  Svc->>Cache: SHA-256 key of type, code, format, theme, scale, renderer
  alt cache hit
    Cache-->>AI: stored result, cache_hit = true
  else miss
    Svc->>Pipe: render
    alt plugin type
      Pipe->>Pipe: render_with_plugin
    else Kroki type
      Pipe->>K: GET /{type}/{format}/{deflate+base64url source}
      K-->>Pipe: SVG or PNG
      opt Kroki fails and fallback is on
        Pipe->>FB: same source
      end
    end
    Pipe-->>Svc: result + attempts + render_ms
    Svc->>Svc: flatten SVG labels, rasterize if PNG was asked for an SVG-only type, build display_markdown
    Svc->>Cache: store
    Svc-->>AI: url, playground, image, display_markdown
  end

Step by step:

1. Type. mrtr.resolve_diagram_type lower-cases the key and accepts it if it is in the catalog. Otherwise, if the client supports form elicitation, the server asks the user to pick from up to eight close matches (difflib, cutoff 0.45); if not, it returns an error with those suggestions. The theme goes through the same treatment.
2. Validation. GenerateUMLInput (Pydantic) checks the arguments; source is limited to MCP_MAX_CODE_LENGTH, 500,000 characters by default. An unknown type returns UNSUPPORTED_DIAGRAM_TYPE with a pointer to uml://types.
3. Format. If the client asks for PNG or JPEG and the type only renders SVG, the service renders SVG and rasterizes it afterwards.
4. Cache. Calls that do not write a file are cached in memory. The key is the SHA-256 of a JSON object holding the type, the trimmed source, format, theme, scale and renderer identity. Defaults: 300 seconds, 128 entries, 32 MiB (MCP_RENDER_CACHE_*).
5. Render. Plugin types (plugin: backend) render locally. Everything else goes to Kroki: the source is compressed with zlib at level 9, base64url-encoded and put in the URL {kroki}/{type}/{format}/{encoded}, which is also the link returned to the user.
6. Fallback. If Kroki fails, PlantUML-family sources are retried on the PlantUML server and Mermaid on mermaid.ink. Mermaid has a fail-fast Kroki deadline of 8 seconds, and a circuit breaker skips Kroki’s Mermaid engine for 60 seconds after repeated failures. Fallback is off by default on Vercel and with a local Kroki, where the public services would be the wrong target.
7. Answer. HTML-backed labels in SVG (foreignObject) are converted to plain SVG text so the file renders anywhere, display_markdown is built for chat, and every result carries attempts, fallback_used and render_ms, so a failure says which backend failed and why.

5. Operations

uml-mcp admin opens a web console on http://127.0.0.1:8765/admin (on a deployed server, /admin): setup, settings, activity, live logs, metrics, rate limits, tools and plugins, clients and quality checks. Locally, changes need a one-time setup token; with enterprise sign-in (Entra ID) the console is read-only unless writes are enabled in the settings.

6. Getting started

Use the hosted server in any MCP client:

"uml-mcp": {
  "transport": "http",
  "url": "https://uml-mcp.vercel.app/mcp"
}

Or install it locally and let the setup command write the client configuration:

uv tool install uml-mcp && uml-mcp setup

Then ask the assistant for a diagram, for example “Draw a sequence diagram of a user logging in through an API gateway.” The repository has ready-made configurations for Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json), Codex, Claude Desktop and Open WebUI, and docs/installation.md covers Docker, Helm and running from source.

7. Repository guide

• server.py, app.py: stdio and HTTP entry points; server.py resolves the MCP object lazily so importing it prints nothing on stdout, which carries the stdio protocol.
• mcp_core/tools/: the tool functions, their schemas, elicitation helpers (mrtr.py), batch progress notifications and export.
• mcp_core/core/: catalog, validation, rendering pipeline, render cache, SVG rasterizing, themes and configuration.
• mcp_core/plugins/, examples/plugins/: the plugin loader and the four bundled plugins (D3, stack diagram, archify, LLM visualizer).
• mcp_core/apps/: the MCP App viewer (ui://uml-mcp/diagram-viewer) and SVG sanitizing.
• mcp_core/admin/, mcp_core/auth/, mcp_core/observability/: admin console, SSO and metrics.
• tools/kroki/: the Kroki client, URL encoding, playground links and per-language helpers.
• deploy/helm/, Dockerfile, docker-compose*.yml, vercel.json: deployment.
• tests/: 127 entries, unit and integration tests with MCP and HTTP rigs.

8. Limits

• Kroki-backed types depend on a reachable Kroki instance, and because the source travels in the URL, very large diagrams produce very long links.
• The render cache is per process and in memory, so it is not shared between serverless instances.
• The fallbacks send diagram source to third-party services (PlantUML server, mermaid.ink) when enabled; set MCP_DIAGRAM_FALLBACK=false if the source is private.
• MCP Apps support varies by client; other clients only get the image and links.

9. Sources

• GitHub repository
• Documentation
• PyPI package
• mcp_core/tools/diagram_tools.py
• mcp_core/core/diagram_service.py
• mcp_core/core/diagram_rendering.py
• mcp_core/core/render_cache.py
• tools/kroki/kroki.py
• Companion article

flowchart LR
  subgraph wf0["Build Package"]
    direction LR
    wf0_build[["build<br/>ubuntu-latest"]]
  end
  subgraph wf1["UML-MCP CD Pipeline"]
    direction LR
    wf1_prepare["prepare<br/>ubuntu-latest"]
    wf1_build["build<br/>reuses build.yml"]
    wf1_deploy["deploy<br/>reuses deploy.yml"]
  end
  subgraph wf2["UML-MCP CI Pipeline"]
    direction LR
    wf2_lint["lint<br/>ubuntu-latest"]
    wf2_test[["test<br/>ubuntu-latest"]]
    wf2_public_kroki["public-kroki<br/>ubuntu-latest"]
    wf2_helm[["helm<br/>ubuntu-latest"]]
    wf2_frontend["frontend<br/>ubuntu-latest"]
    wf2_build["build<br/>reuses build.yml"]
  end
  subgraph wf3["Deploy (Vercel conformance + Smithery publi…"]
    direction LR
    wf3_test_and_publish[["test-and-publish<br/>ubuntu-latest"]]
  end
  subgraph wf4["Deploy docs"]
    direction LR
    wf4_build[["build<br/>ubuntu-latest"]]
    wf4_deploy[["deploy<br/>ubuntu-latest"]]
  end
  subgraph wf5["MCP 2026 Conformance"]
    direction LR
    wf5_protocol_conformance[["protocol-conformance<br/>ubuntu-latest"]]
  end
  t0(["manual run · called by a workflow"])
  t1(["push · release · manual run"])
  t2(["manual run · push · pull request"])
  t3(["called by a workflow · manual run"])
  t4(["push · manual run"])
  t5(["manual run · pull request"])
  d0[("GitHub Pages")]
  t0 --> wf0_build
  t1 --> wf1_prepare
  wf1_prepare --> wf1_build
  wf1_build --> wf1_deploy
  t2 --> wf2_lint
  t2 --> wf2_test
  t2 --> wf2_public_kroki
  t2 --> wf2_helm
  t2 --> wf2_frontend
  t2 --> wf2_build
  t3 --> wf3_test_and_publish
  t4 --> wf4_build
  wf4_build --> wf4_deploy
  wf4_deploy -.-> d0
  t5 --> wf5_protocol_conformance

flowchart LR
  repo[("GitHub repository")]
  ci[["GitHub Actions<br/>11 workflows"]]
  image["Docker image<br/>FROM python:3.15-slim"]
  pub_GitHub_Pages[("GitHub Pages")]
  pub_PyPI[("PyPI")]
  host_Vercel("Vercel<br/>vercel.json")
  host_Kubernetes_manifests("Kubernetes<br/>deploy/helm/uml-mcp/")
  host_MkDocs_site("Documentation site (MkDocs)<br/>mkdocs.yml")
  subgraph compose["Docker Compose"]
    svc_uml_mcp["uml-mcp"]
    svc_kroki["kroki"]
    svc_mermaid["mermaid"]
    svc_blockdiag["blockdiag"]
    svc_bpmn["bpmn"]
    svc_excalidraw["excalidraw"]
    svc_plantuml_server["plantuml-server"]
    svc_mermaid_ink["mermaid-ink"]
  end
  repo -->|"push or pull request"| ci
  ci -->|"docker build"| image
  ci -->|"publishes"| pub_GitHub_Pages
  ci -->|"publishes"| pub_PyPI
  ci -.->|"configured"| host_Vercel
  ci -.->|"configured"| host_Kubernetes_manifests
  ci -.->|"configured"| host_MkDocs_site
  image -->|"docker compose up"| compose