UML-MCP is a diagram generation server that exposes an MCP endpoint for clients to request diagrams in various formats. It supports UML diagram types (Class, Sequence, Activity, Use Case, State, Component, Deployment, Object) as well as other diagram formats via backends like Mermaid and D2, with optional rendering through Kroki or PlantUML servers. You can access the MCP endpoint through HTTP and use the server as a drop-in renderer for AI assistants or other MCP clients. The server can output SVG, PNG, PDF, JPEG (where supported), and provides text/base64 representations when supported by the backend. To run locally, start the Python MCP server and, if needed, configure local rendering backends (Kroki and/or PlantUML).

Once running, you can connect an MCP client and issue requests to /mcp. The server supports various diagram types and backends, and can automatically fall back to alternative renderers if a preferred backend is unavailable. Tools such as listing available capabilities or starting the server with HTTP transport are available via the command line (for example, python server.py --transport http --host 127.0.0.1 --port 8000).

Prerequisites:

• Python 3.10+ installed on your system
• Git installed
• Optional: uv (for development) or Poetry if you prefer using those tools

Installation steps:

1. Clone the repository: git clone https://github.com/antoinebou12/uml-mcp.git cd uml-mcp

2. Install dependencies:

   • Using uv (recommended for modern Python): uv sync
   • Or using Poetry: poetry install
   • Or in editable mode with pip: pip install -e .

3. Optional development tools: uv sync --all-groups

   or: poetry install --with dev

   or: pip install -e ".[dev]""

4. Run the MCP server: python server.py

   Or with HTTP transport and explicit host/port:

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

5. (Optional) If you want local backends, start Kroki and/or PlantUML containers as described in the Local development section, then configure environment variables accordingly (USE_LOCAL_KROKI, KROKI_SERVER, USE_LOCAL_PLANTUML, PLANTUML_SERVER).

Note: The server can also be started via the FastMCP CLI if you have a fastmcp.json config present. Ensure your environment matches the prerequisites above before proceeding.

Environment variables and configuration options:

• MCP_OUTPUT_DIR or UML_MCP_OUTPUT_DIR: Directory to write generated diagrams
• KROKI_SERVER: URL of your Kroki instance (default https://kroki.io)
• PLANTUML_SERVER: URL of a PlantUML server (default http://plantuml-server:8080)
• USE_LOCAL_KROKI / USE_LOCAL_PLANTUML: Use local rendering services instead of remote ones
• LOG_LEVEL: Logging level, e.g., INFO, DEBUG, WARNING

Common issues:

• If you see 401/403 on VercelSmithery deployments, check Deployment Protection or OAuth settings for your hosting provider.
• When running locally, ensure backends (Kroki/PlantUML) are reachable at the configured URLs.
• If the MCP cannot write to disk on some hosts, you can rely on Kroki or return diagram URLs via kroki_encode as a fallback.

Configuration tips:

• Start with USE_LOCAL_KROKI=false and USE_LOCAL_PLANTUML=false, then enable local backends if you need to avoid external dependencies.
• Use the config blocks under config/ as examples for client-side MCP configuration.