Skip to content
← All articles
Project introduction

uml-mcp — UML diagrams from chat via MCP

Listen to the audio story

uml-mcp: ask your assistant for a diagram · 2:21 · AI-written script, synthetic voices

Transcript

Ava: You type a sentence in chat, and a clean sequence diagram appears. That's what Antoine's open source project, uml-mcp, makes possible.

Andrew: How does the assistant draw diagrams?

Ava: Through MCP, the Model Context Protocol, which lets an assistant call real tools. uml-mcp is a server with diagram tools: the assistant writes the diagram source in Mermaid, PlantUML or another supported format, and the server sends back a rendered image and useful links.

Andrew: Think of the assistant as an architect and uml-mcp as the printing shop.

Ava: Perfect picture. The architect hands over a sketch in text form, and the shop returns the blueprint.

Andrew: What's inside?

Ava: Five documented tools: generate a diagram, generate an image, validate the source, list the available diagram types, and render several at once. Through Kroki it covers around thirty-seven types.

Andrew: How do the editable links work?

Ava: For Mermaid, the code builds a small JSON state, compresses it with zlib and encodes it in URL-safe base64. That one state powers both an image link and an editable mermaid dot live link. It also picks the right endpoint for SVG versus PNG, JPEG or WebP.

Andrew: Why MCP rather than the earlier tools?

Ava: Antoine started with a ChatGPT diagram plugin and AIPRM sequence templates. Both work, but he wanted native tools: enable a server once, call generate UML from the agent, and save the Mermaid file and SVG beside a blog post. MCP is that layer. The plugin idea is the same, but the host is different.

Andrew: How do you set it up in Cursor?

Ava: Install from the GitHub repository, add the server to Cursor's MCP settings, then ask for a specific type, like a Mermaid sequence with a user, React, FastAPI and Postgres. There's also a hosted endpoint and a docs site.

Andrew: Anything for the operator?

Ava: An admin command, metrics, and a Kroki playground that make it easy to see what the renderer is doing.

Andrew: Where is it used?

Ava: Antoine uses it across his blog for pipeline and career diagrams. The full post has a sequence diagram of the flow and links to the project page.

A Mermaid client/server sequence rendered in chat, from the repository
Table of contents

GitHub stars[1]

uml-mcp[1] gives an MCP client real diagram tools: an assistant supplies Mermaid, PlantUML, or another supported diagram source, and the server returns rendered output and useful links. The current repository documents five tools and a catalog of roughly 37 Kroki-backed types. Those counts describe the documented interface, not a rendering benchmark.

sequenceDiagram
  participant C as MCP client
  participant U as UML-MCP
  participant R as Renderer
  C->>U: generate_uml with source and type
  U->>U: Check request
  U->>R: Build rendering request
  R-->>U: Rendered diagram
  U-->>C: URL, editor link or image

tools/kroki/mermaid.py[2] builds JSON state, compresses it with zlib, and encodes it as URL-safe base64. That state supports both an image link and an editable mermaid.live link.

The module distinguishes SVG at /svg/ from PNG/JPEG/WebP at /img/?type=.... A wrong endpoint can break a perfectly valid diagram before its syntax ever becomes the problem.

The repository also exposes generate_uml_image, validate_uml, list_diagram_types, and generate_uml_batch. Choose the tool for inline preview, source checks, format discovery, or multiple independent renders.

2. There is an operations side too

The current README documents uml-mcp admin, metrics, and a Kroki playground. They help separate invalid source, unavailable renderers, and configuration problems. A successful request still needs a human check that the diagram represents the intended system.

For the same diagram-source idea inside a node editor, see ComfyUI-UML.

3. Why MCP instead of copy-paste templates?

I started with ChatGPT plugins (D2C OpenAI diagram plugin) and AIPRM sequence templates. Both work, but editors wanted native tools: enable a server once, call generate_uml from the agent, save .mmd + SVG beside the post. MCP is that layer — same idea as the plugin, different host.

4. What it supports

BackendGood for
MermaidGitHub-native flows, quick sequences
PlantUMLClassic UML, deployments, strict notation
KrokiUnified render path when you mix formats

Hosted endpoint: uml-mcp.vercel.app/mcp[3]. Docs site: antoinebou12.github.io/uml-mcp[4].

5. Cursor setup (short)

  1. Clone or install from github.com/antoinebou12/uml-mcp[1] (README has the MCP config block).
  2. Add the server to Cursor MCP settings.
  3. Ask for a diagram type explicitly — e.g. “Mermaid sequence: user, React, FastAPI, Postgres, login with cache miss.”

I use it across this blog for pipeline and career diagrams; see AI figurines post or software engineering journey for examples.

6. Limits

  • Models still hallucinate syntax sometimes — always render locally before publishing.
  • Secrets belong out of prompts; diagram user/service names, not production credentials.
  • OpenAI plugin churn moved the ChatGPT story toward Custom GPT + MCP; treat the D2C plugin post as historical context with a live successor.

7. Project page

More badges and links: uml-mcp project page.

References

  1. antoinebou12. (). uml-mcp. [Software repository] github.com.
  2. antoinebou12. (). tools/kroki/mermaid.py. [Source file or documentation] github.com.
  3. uml-mcp.vercel.app/mcp. (). [Web page] uml-mcp.vercel.app.
  4. antoinebou12.github.io/uml-mcp. (). [Web page] antoinebou12.github.io.

References use this article’s publication date.