UML-MCP: Diagram Generation via MCP

Generate UML and other diagrams through the Model Context Protocol.

At a glance

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

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

MCP Tools and Resources

Tools

Resources (uml://)

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:

• Online: antoinebou12.github.io/uml-mcp
• Local: uv run mkdocs serve then open http://127.0.0.1:8000

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.

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.

Full options: docs/configuration.md

License

MIT