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

Requirement	Version	Note
StarUML	v6.0.0+	https://staruml.io/
Python	3.10+	https://www.python.org/downloads/
staruml-controller	latest	StarUML 扩展，提供 REST API

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)

Tool	Description	Supported Types
generate_diagram	Import any Mermaid code	classDiagram, sequenceDiagram, flowchart, erDiagram, mindmap, requirementDiagram, stateDiagram

Structured Diagram Builders

Tool	Description
create_class_diagram	类图 — classes, attributes, methods, relationships
create_sequence_diagram	时序图 — participants, messages
create_use_case_diagram	用例图 — actors, use cases, relationships
create_activity_diagram	活动图 — nodes, flows
create_state_diagram	状态图 — states, transitions
create_er_diagram	ER 图 — entities, attributes, relationships
create_flowchart	流程图 — nodes, connections
create_mindmap	思维导图 — root, branches

Utility Tools

Tool	Description
check_staruml_connection	检查与 StarUML 的连接状态
get_all_diagrams	获取当前项目所有图表信息
get_current_diagram	获取当前图表详情
export_diagram_as_image	导出图表为 PNG 图片（base64）

---

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:

Family	Prefix	Examples
Use Case	/api/usecase/	actors, use-cases, subjects, associations, includes, extends
Class	/api/class/	classes, interfaces, attributes, methods, associations
Sequence	/api/sequence/	lifelines, messages, combined-fragments
Activity	/api/activity/	actions, decisions, forks
State Machine	/api/statemachine/	states, transitions
ERD	/api/erd/	entities, columns, relationships
Flowchart	/api/flowchart/	nodes, connections
MindMap	/api/mindmap/	nodes
BPMN	/api/bpmn/	pools, lanes, tasks, gateways
C4	/api/c4/	containers, components, relationships
AWS / Azure / GCP	/api/aws/, /api/azure/, /api/gcp/	architecture diagrams

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