GitUML — Java / Spring Boot UML Generator + MCP Server

Generate UML class diagrams, sequence diagrams, flowcharts, and component diagrams from any Java or Spring Boot repository — via CLI or directly inside Claude Desktop as an MCP server.

Features

• 5 MCP tools exposed to Claude Desktop: analyze_repo, generate_class_diagram, generate_sequence_diagram, generate_flowchart, generate_component_diagram

• Works with GitHub/GitLab URLs (shallow clone) or local paths

• Detects project type: pure_java, spring_boot, spring_mvc

• Detects build system: maven, gradle, none

• Annotation-aware Spring layer detection (Controller → Service → Repository → Model → Config → Messaging)

• Output in Mermaid, PlantUML, or both

• Test directories excluded by default

Related MCP server: UML-MCP Server

Project Structure

gituml/
├── server.py              ← MCP server (FastMCP, STDIO transport)
├── main.py                ← CLI entry point (argparse)
├── test_server.py         ← Quick smoke-test for server tools
├── requirements.txt
├── core/
│   ├── models.py          ← Data models: ClassMeta, MethodMeta, RepoMetadata, …
│   └── java_parser.py     ← javalang-based Java AST parser
└── diagrams/
    ├── class_diagram.py
    ├── sequence_diagram.py
    ├── flowchart.py
    └── component_diagram.py

Requirements

• Python 3.10+

• Git installed and available on PATH (needed for cloning remote repos)

pip install -r requirements.txt

requirements.txt installs:

Usage — CLI

# From a GitHub URL
python main.py --repo https://github.com/spring-projects/spring-petclinic

# From a local path
python main.py --repo /path/to/my-spring-app

# With sequence diagram entry point
python main.py --repo /path/to/my-app \
               --entry-class UserController \
               --entry-method createUser

# With method-level flowchart
python main.py --repo /path/to/my-app \
               --flow-class OrderService \
               --flow-method processOrder

# Custom output directory, Mermaid only
python main.py --repo /path/to/my-app --output-dir ./diagrams --format mermaid

# Include test directories
python main.py --repo /path/to/my-app --include-tests

# Limit class diagram to 30 classes
python main.py --repo /path/to/my-app --max-classes 30

CLI Arguments

Output Files

All written to ./output/ by default:

output/
├── class_diagram.md
├── component_diagram.md
├── sequence_diagram.md
└── flowchart.md

Preview .md files in VS Code with the Markdown Preview Enhanced extension (Ctrl+Shift+V / Cmd+Shift+V).

Usage — MCP Server (Claude Desktop)

Step 1 — Install Claude Desktop

Download from https://claude.ai/download

Step 2 — Locate the config file

Step 3 — Register GitUML

Open the config file and add the gituml entry:

Windows

{
  "mcpServers": {
    "gituml": {
      "command": "python",
      "args": ["C:\\Users\\YourName\\projects\\gituml\\server.py"]
    }
  }
}

macOS / Linux

{
  "mcpServers": {
    "gituml": {
      "command": "python3",
      "args": ["/home/yourname/projects/gituml/server.py"]
    }
  }
}

Windows note: Use double backslashes \\ in paths inside JSON.

Step 4 — Restart Claude Desktop

After saving the config, fully quit and relaunch Claude Desktop.

in the chat input bar — Ask for available tools and it should return the following:

• analyze_repo

• generate_class_diagram

• generate_sequence_diagram

• generate_flowchart

• generate_component_diagram

• generate_all

Step 5 — Talk to Claude

Analyse this repo: https://github.com/spring-projects/spring-petclinic

Generate a class diagram for C:/projects/my-spring-app

Show me the sequence diagram for UserController.createUser

Generate a flowchart for the processOrder method in OrderService

Show the component architecture of https://github.com/myorg/myrepo

Generate all diagrams for https://github.com/user/repo and save to ./output

MCP Tools Reference

analyze_repo

Returns a structured summary of the repository — no diagrams generated.

Returns: Project type, build system, package list, layer breakdown, dependency graph.

generate_class_diagram

Generates a UML class diagram showing classes, fields, methods, inheritance, and Spring layers.

generate_sequence_diagram

Traces the call chain from an entry point across Spring layers.

generate_flowchart

Generates a control-flow diagram for a specific method, or a high-level architecture flowchart.

generate_component_diagram

High-level architecture view — components grouped by Spring layer or package.

generate_all

Generates all 4 diagrams and writes them to disk — equivalent to running main.py from the CLI.

Supported

Troubleshooting

No Java classes found — Confirm the path points to a Java project root. Check that .java files exist under src/.

Failed to clone repo — Verify git is on your PATH and the URL is accessible. Private repos require SSH key or credential setup.

gitpython not installed — Run pip install gitpython.

Claude Desktop tools not appearing — Check the JSON config for syntax errors (trailing commas, wrong path separators on Windows). Fully quit and relaunch Claude Desktop.

MCP server not starting — Test the server directly: python server.py — it should block silently (waiting on STDIO). Any Python import errors will surface here.