StarUML MCP Server

通过 MCP 协议或 REST API 远程控制 StarUML，让 AI 自动生成各种 UML 图表（用例图、类图、时序图、ER 图等）。

Architecture

AI Client (Claude/Hermes/Cursor)
    │  MCP Protocol (stdio)
    ▼
Python MCP Server (server.py)
    │  HTTP REST API
    ▼
staruml-controller Extension (runs inside StarUML)
    │
    ▼
StarUML — renders diagrams

Prerequisites

Quick Start

1. Install staruml-controller extension

Clone into StarUML's extensions directory:

# Windows (%APPDATA% = C:\Users\<用户名>\AppData\Roaming)
cd %APPDATA%\StarUML\extensions\user
git clone https://github.com/pontasan/staruml-controller.git

# macOS
cd ~/Library/Application\ Support/StarUML/extensions/user
git clone https://github.com/pontasan/staruml-controller.git

# Linux
cd ~/.config/StarUML/extensions/user
git clone https://github.com/pontasan/staruml-controller.git

2. Install Python dependencies

cd staruml-mcp
pip install -r requirements.txt

Or run the setup script:

scripts\setup.bat

3. Start StarUML

Launch StarUML — the extension auto-starts and listens on port 12345.

4. Start MCP Server

python server.py

Configure AI Clients

Proma / Claude Desktop

Edit claude_desktop_config.json (or Proma's mcp.json):

{
  "mcpServers": {
    "staruml": {
      "command": "python",
      "args": ["D:/path/to/staruml-mcp/server.py"],
      "timeout": 60
    }
  }
}

Hermes Agent

Edit ~/.hermes/config.yaml:

mcp_servers:
  staruml:
    command: "python"
    args: ["D:/path/to/staruml-mcp/server.py"]
    timeout: 60

Cursor

Edit .cursor/mcp.json:

{
  "mcpServers": {
    "staruml": {
      "command": "python",
      "args": ["D:/path/to/staruml-mcp/server.py"]
    }
  }
}

Custom Port

If the staruml-controller uses a different port:

python server.py --api-port 56789

MCP Tools Reference

Diagram Generation (via Mermaid)

Structured Diagram Builders

Utility Tools

AI Prompt Examples

In your AI chat, just say:

"用 staruml 画一个电商系统的用例图，有顾客、商家和管理员三个角色"

"画一个图书管理系统的类图，包含 Book、User、BorrowRecord"

"画一个用户登录的时序图"

"画一个订单处理的状态图"

"画一个数据库设计的 ER 图"

Direct REST API Usage

The scripts/ directory contains standalone Python scripts that call the REST API directly (no MCP client needed).

Create Use Case Diagram

python create_usecase.py

Layout / Reposition Elements

If diagram elements overlap, run the layout script:

python layout_usecase.py

Note: staruml-controller's auto-layout skips use case diagrams, so layout is done by manually positioning views via PUT /api/views/:id.

API Endpoints

staruml-controller provides full CRUD REST API for all diagram families:

Each family supports: GET/POST /api/{family}/{resource}, GET/PUT/DELETE /api/{family}/{resource}/:id

Project Structure

staruml-mcp/
├── server.py                    # MCP Server (Python / FastMCP)
├── requirements.txt             # Python dependencies
├── README.md                    # This file
├── .gitignore
│
├── create_usecase.py            # Standalone: create a use case diagram via REST API
├── layout_usecase.py            # Standalone: reposition diagram elements
│
├── scripts/
│   ├── setup.bat                # Windows setup script
│   └── test_connection.bat      # Connection test script
│
└── examples/
    ├── class_library.json        # Class diagram example data
    ├── sequence_login.json       # Sequence diagram example data
    └── use_case_ecommerce.json   # Use case diagram example data

Troubleshooting

"Cannot connect to StarUML Controller"

1. Ensure StarUML is running

2. Check staruml-controller is installed at %APPDATA%\StarUML\extensions\user\staruml-controller

3. Restart StarUML (extension auto-starts on port 12345)

4. Run scripts\test_connection.bat to verify

Mermaid Import Fails

Only these Mermaid types are supported: classDiagram, sequenceDiagram, flowchart, erDiagram, mindmap, requirementDiagram, stateDiagram. Use case diagrams use the REST API directly instead.

Port Conflict

If port 12345 is in use, modify server.py's DEFAULT_API_PORT or pass --api-port flag.

Diagram Elements Overlap

Run python layout_usecase.py to reposition use case diagram elements. For other diagram types, use POST /api/diagrams/{id}/layout with direction (TB/BT/LR/RL).

License

MIT