Skip to main content
Glama
Sign In
UML-MCP

UML-MCP

by Ron-RONZZ-org
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

UML-MCP: Diagram Generation via MCP

Run Tests Build Package Deploy docs GitHub stars License: MIT Python >=3.12,<3.13 MCP status

Generate UML and other diagrams through the Model Context Protocol.

At a glance

Topic

What you get

Diagrams

30+ types: UML (Class, Sequence, Activity, Use Case, State, Component, Deployment, Object), Mermaid, D2, Graphviz, TikZ, ERD, BlockDiag, BPMN, C4, and more via Kroki

MCP tools

generate_uml, validate_uml, list_diagram_types, generate_uml_batch

Outputs

SVG, PNG, PDF, JPEG, base64 (availability varies by diagram type)

Pipeline

Kroki first, then PlantUML or Mermaid.ink

Deployment

Local stdio, local HTTP, Docker, Vercel, Smithery

Source

URL

Live MCP (HTTP)

https://uml-mcp.vercel.app/mcp

Smithery catalog

Add via Smithery

Quick Start

Choose your mode

  • Remote (recommended): Fast setup over HTTP MCP with Vercel serverless runtime

  • Local: stdio process for file output and local debugging

Remote quick start (Vercel HTTP MCP)

Configuration for the public Vercel deployment:

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

Local quick start (stdio MCP)

git clone https://github.com/antoinebou12/uml-mcp.git && cd uml-mcp
uv sync
uv run python server.py

Example client configs:

  • config/cursor_config.json

  • config/claude_desktop_config.json

  • config/README.md for exact config file locations

  • Claude Code: install the bundled plugin from the repo marketplace (see below) or read docs/integrations/claude_code.md

Claude Code plugin

Adds the hosted HTTP MCP server plus a diagram skill (no settings.json paste). In Claude Code:

/plugin marketplace add https://github.com/antoinebou12/uml-mcp
/plugin install uml-mcp@uml-mcp-plugins

Use a local path instead of the GitHub URL if you already cloned this repo. Custom endpoints and validation: docs/integrations/claude_code.md.

Related MCP server: UML-MCP

Remote vs Local

  • Transport: Remote uses HTTP MCP, local uses stdio by default

  • Runtime: Remote runs on Vercel, local runs in your Python environment

  • File writes: Remote is read-only (no output_dir), local supports output_dir

  • Returned data: Both return URL + base64; local can also save files

  • Environment variables: Remote is managed server-side; local reads your env config

MCP clients must call /mcp, not the site root.

Supported Diagram Types

Category

Examples

UML (PlantUML)

Class, Sequence, Activity, Use Case, State, Component, Deployment, Object

General

Mermaid, D2, Graphviz, ERD, BlockDiag, BPMN, C4

Specialized

TikZ, Excalidraw, Nomnoml, Pikchr, Structurizr, SVGBob, WaveDrom, WireViz, …

Full list with supported formats: run python server.py --list-tools or query uml://types and uml://formats.

MCP Tools and Resources

Tools

Tool

Purpose

generate_uml

Render a diagram; omit output_dir for URL/base64 only

validate_uml

Structural validation before render; strict enables extra Mermaid/D2 checks

list_diagram_types

Same metadata as uml://types when resources are awkward

generate_uml_batch

Multiple diagrams in one call (cap: MCP_BATCH_MAX_ITEMS)

Resources (uml://)

Resource

Description

uml://types

Diagram types, backends, supported formats per type

uml://templates

Starter templates per type; see BPMN 2.0.2 guide for element and flow reference (docs)

uml://examples

Example diagrams per type; Mermaid documents named samples (sequence API, Gantt) alongside uml://examples (key mermaid)

uml://formats

Output formats per type

uml://capabilities

Type → backend → formats matrix used for validation

uml://server-info

Server name, version, tools, prompts, Kroki/PlantUML URLs

uml://workflow

Recommended plan-then-generate workflow

Deployment

Vercel

This repo includes vercel.json for serverless deployment.

  1. Connect the repo to Vercel

  2. Use https://<project>.vercel.app/mcp

  3. Keep /mcp in all MCP client URLs

Smithery

  1. Open smithery.ai/new, choose URL

  2. Enter https://<project>.vercel.app/mcp

  3. Configure display name, description, and homepage

Detailed guide: docs/integrations/vercel_smithery.md

Docker

Default image serves FastAPI on port 8000 with MCP HTTP at http://127.0.0.1:8000/mcp.

# Full local stack (local Kroki + mermaid + blockdiag)
docker compose up -d

# API + MCP only (public Kroki)
docker build -t uml-mcp . && docker run -p 8000:8000 uml-mcp

# stdio MCP subprocess mode
docker run -i uml-mcp python server.py --transport stdio

Configuration (Local runtime)

These variables apply to local/self-hosted runs. Remote Vercel endpoint settings are managed server-side.

Variable

Description

Default

KROKI_SERVER

Kroki server URL

https://kroki.io

PLANTUML_SERVER

PlantUML server URL

http://plantuml-server:8080

MCP_OUTPUT_DIR

Diagram output directory

./output

MCP_READ_ONLY

Disable file writes

false

MCP_MAX_CODE_LENGTH

Max diagram code length

500000

MCP_BATCH_MAX_ITEMS

Max items per generate_uml_batch

20

MCP_RATE_LIMIT_PER_MINUTE

HTTP rate limit per IP for diagram/MCP routes (0 = off)

0

USE_LOCAL_KROKI

Use local Kroki instance

false

USE_LOCAL_PLANTUML

Use local PlantUML instance

false

Full options: docs/configuration.md

Architecture

Typical flow when a user asks an MCP-enabled assistant for a diagram: the assistant calls generate_uml, the server renders via Kroki, then returns URLs and optional base64 to the assistant for the user.

server.py              -- MCP entry point (stdio/HTTP)
app.py                 -- FastAPI REST API + MCP HTTP at /mcp
api/app.py             -- legacy re-export of root app (Vercel FastAPI preset uses root app.py)
mcp_core/
  core/                -- config, server, CLI, utilities, diagram pipeline
  tools/               -- generate_uml, validate_uml
  prompts/             -- diagram generation prompts
  resources/           -- uml:// resource handlers
tools/kroki/           -- Kroki, PlantUML, Mermaid, D2 clients

Development

# Install dev dependencies
uv sync --all-groups

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check . && uv run ruff format --check .

# Local CI
make ci

Documentation

Built with MkDocs + Material:

Contributing

License

MIT

Acknowledgements

PlantUML | Kroki | Mermaid | D2

Star History

GitHub Star History

Updated daily by GitHub Actions from GitHub's timestamped stargazer API. The refresh job prefers the optional STAR_HISTORY_TOKEN repository secret and safely falls back to the per-run GITHUB_TOKEN.

Available Tools

5 tools
generate_umlGenerate UmlA
Idempotent

Generate any UML or diagram by type (class, sequence, mermaid, d2, etc.)

Inputs: code (required), diagram_type (required), scale, theme, +2 more. Returns: object

generate_uml_batchGenerate Uml BatchA
Idempotent

Generate multiple diagrams in one call. Each item is like generate_uml (diagram_type, code, output_format?, theme?, scale?). Optional shared output_dir for all items. Returns a list of per-index results or errors.

Inputs: items (required), output_dir. Returns: object

list_diagram_typesList Diagram TypesA
Read-onlyIdempotent

List supported diagram types with Kroki backend, description, and formats (same data as uml://types resource). Use when the client cannot read resources.

Inputs: no named parameters. Returns: object

render_diagramRender DiagramA
Idempotent

Render a diagram and return it as an MCP image plus the server-side file path. Use this instead of generate_uml when the figure should appear in chat or be uploaded: the image needs no base64 copying in the conversation, and local_path is a file the wiki writer can upload directly.

Inputs: code (required), diagram_type (required), scale, theme, +1 more. Returns: result

validate_umlValidate UmlA
Read-onlyIdempotent

Validate a diagram by compiling it on the renderer. Runs local structure checks first, then a real Kroki compile, so valid reflects what the renderer accepts (a TikZ figure that does not compile is reported invalid). Returns errors, suggestions, compiled, and compile_ms.

Inputs: code (required), diagram_type (required), strict, output_format. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool has a mostly distinct role: listing types, single generate, batch generate, validate, and render. The main ambiguity is between generate_uml and render_diagram, but the description explicitly steers usage ('use this instead of generate_uml when the figure should appear in chat'), which resolves most misselection risk.

    Naming Consistency4/5

    All names follow a snake_case verb_noun pattern (list_diagram_types, generate_uml, generate_uml_batch, validate_uml, render_diagram). Minor inconsistency: three tools use the '_uml' resource suffix while render_diagram uses '_diagram', but the convention remains readable and predictable.

    Tool Count5/5

    Five tools is well-scoped for a diagram generation server, with each tool earning its place (discovery, single gen, batch gen, validation, image rendering). No obvious padding or redundancy.

    Completeness4/5

    The core lifecycle (discover types, generate, batch, validate, render to image/file) is covered with no dead ends. Minor gaps exist around managing generated artifacts (e.g., listing or cleaning up previously written output files), but agents can work around this.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers