uml-mcp

UML-MCP User Manual

This manual walks you through installing, configuring, and using the UML-MCP diagram server with your AI assistant or MCP client.

What is UML-MCP?

UML-MCP is a diagram generation server that speaks the Model Context Protocol (MCP). It lets AI assistants (Cursor, Claude Desktop, etc.) create diagrams for you—UML (class, sequence, activity, use case, state, component, deployment, object), Mermaid, D2, Graphviz, ERD, and more—using PlantUML, Kroki, and other backends.

Quick start (no install)

  1. Add the server via Smithery (e.g. for Claude Desktop): 
    npx -y @smithery/cli install antoinebou12/uml --client claude
  2. Restart your AI client and ask it to create a diagram, e.g.:
    • “Create a class diagram for a banking app with Account, Customer, and Transaction.”
    • “Draw a sequence diagram for user login with validation and session creation.”

Diagrams are generated by the server; the assistant shows you the image or link. For Cursor, use the same Smithery flow or add the server URL in Cursor’s MCP settings (see Configuration below).

Installation (local server)

Requirements

Steps

  1. Clone and install (from project root):

    With uv:

    git clone https://github.com/antoinebou12/uml-mcp.git
cd uml-mcp
uv sync

    With Poetry:

    git clone https://github.com/antoinebou12/uml-mcp.git
cd uml-mcp
poetry install

    With pip:

    git clone https://github.com/antoinebou12/uml-mcp.git
cd uml-mcp
pip install -e .
  2. Verify (optional): 
    python server.py --list-tools

    You should see the server name and the diagram tools generate_uml and generate_diagram_url.

  3. Run the server (your MCP client will start it automatically when configured; for manual check): 
    python server.py

    Default is stdio. For HTTP (e.g. custom hosting):

    python server.py --transport http --host 127.0.0.1 --port 8000

See Installation and Deploy to Vercel and Smithery for more options (Docker, Vercel, etc.).

Configuration

1. MCP client (Cursor / Claude Desktop)

Your client must know how to start UML-MCP (command + args + working directory) or, for HTTP, the server URL.

Config file locations:

Client Config file (typical)
Cursor %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json (Windows) or Cursor Settings → MCP
Claude Desktop %APPDATA%\Claude\claude_desktop_config.json (Windows), ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Example (stdio, local install):
Use the snippets in config/ in this repo and replace /path/to/uml-mcp with your actual path.

Cursor (local server):

{
  "mcpServers": {
    "UML-MCP-Server": {
      "command": "python",
      "args": ["C:\\path\\to\\uml-mcp\\server.py"],
      "cwd": "C:\\path\\to\\uml-mcp"
    }
  }
}

Claude Desktop (local server):

{
  "mcpServers": {
    "uml-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\uml-mcp\\server.py"],
      "cwd": "C:\\path\\to\\uml-mcp"
    }
  }
}

Optional: set where diagrams are saved:

"env": { "MCP_OUTPUT_DIR": "C:\\path\\to\\diagrams" }

Details: config/README.md, Cursor integration, Claude Desktop integration.

2. Environment variables (optional)

Variable Description Default
MCP_OUTPUT_DIR / UML_MCP_OUTPUT_DIR Directory for generated diagrams ./output
KROKI_SERVER Kroki server URL https://kroki.io
PLANTUML_SERVER PlantUML server URL http://plantuml-server:8080
USE_LOCAL_KROKI Use local Kroki (true/false) false
USE_LOCAL_PLANTUML Use local PlantUML (true/false) false
LOG_LEVEL Logging level —

Full list: Configuration.

3. Local diagram backends (optional)

For offline use or faster rendering, run PlantUML and/or Kroki locally (e.g. with Docker), then set:

export USE_LOCAL_PLANTUML=true
export PLANTUML_SERVER=http://localhost:8080
export USE_LOCAL_KROKI=true
export KROKI_SERVER=http://localhost:8000

Start the containers:

docker run -d -p 8080:8080 plantuml/plantuml-server
docker run -d -p 8000:8000 yuzutech/kroki

Using the server

In Cursor or Claude Desktop

  1. Restart the app after changing MCP config.
  2. Start a chat and ask for a diagram in natural language. The assistant will call UML-MCP tools and show you the result (image or link).

Example prompts:

You can be specific (“use PlantUML”, “output as PNG”) or let the assistant choose. Output is typically SVG or PNG; you can set output_dir via MCP_OUTPUT_DIR so files are saved where you want.

Tools at a glance

Tool Purpose
generate_uml Generate a diagram; optionally save to output_dir. Params: diagram_type, code, output_dir, output_format, theme, scale.
generate_diagram_url Return diagram URL and base64 image only (no file). Params: diagram_type, code, output_format, theme, scale.

Full reference: API / tools.

Better results for complex diagrams

The default prompts (uml_diagram, uml_diagram_with_thinking) instruct the model to plan first (decide diagram type, purpose, elements, relationships), then output the diagram code and call generate_uml with the chosen diagram_type and final code. The resource uml://workflow describes this flow.

Supported diagram types

Category Types
UML Class, Sequence, Activity, Use Case, State, Component, Deployment, Object
Other Mermaid, D2, Graphviz, ERD, BlockDiag, BPMN, C4 (PlantUML)

Output formats depend on the type (e.g. PlantUML: png, svg, pdf, txt; Mermaid: svg, png). See Configuration – Output formats and UML diagrams for syntax and examples.

Troubleshooting

“Server won’t start” or “Connection failed”

“No diagram / wrong diagram”

Smithery / Vercel: 401 or “Invalid OAuth”

If you added the server via Smithery and get 401 or OAuth errors, the Vercel project may have Deployment Protection enabled. See Vercel & Smithery – Troubleshooting (disable protection or use a bypass token).

More help

Where to go next

This site is open source. Improve this page.