UML-MCP: Diagram Generation via MCP

[![Python >=3.12,

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.

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

Frontend streaming (AG-UI)

`app.py` also serves AG-UI (Agent-User Interaction Protocol) events for frontends that want

to render diagrams inline instead of via click-through URLs: `POST /ag-ui/generate`

(stateless SSE stream), plus the start-then-subscribe pair `POST /ag-ui/start` and

`GET /ag-ui/events/{run_id}`. Integrate with CopilotKit or consume the SSE stream directly

— see docs/integrations/frontend.md.

Resources (`uml://`)

Deployment

Vercel

This repo includes `vercel.json` for serverless deployment.

1. Connect the repo to Vercel

2. Use `https://.vercel.app/mcp`

3. Keep `/mcp` in all MCP client URLs

Smithery

1. Open smithery.ai/new, choose URL

2. Enter `https://.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

# Optional: add a local PlantUML server (opt-in profile, host port 8002)
docker compose --profile plantuml up -d

PlantUML is a fallback renderer, so set `MCP_DIAGRAM_FALLBACK=true` alongside the profile for

UML-MCP to use it. See docs/deploy/docker.md.

Configuration (Local runtime)

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

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:

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

Contributing

• Contributing guide
• Code of conduct
• Security policy

License

MIT

Acknowledgements

PlantUML | Kroki | Mermaid | D2