Staruml MCP

staruml-mcp

Model Context Protocol (MCP) server for StarUML. Lets AI agents (Claude Code, Cursor, VS Code Copilot, Codex) drive StarUML programmatically — generate UML diagrams from Mermaid, execute any built-in command, CRUD elements, save projects, and more.

How it fits together

  AI Agent  ──MCP──►  staruml-mcp (this package)  ──HTTP──►  StarUML

:58321 (built-in, 4 tools) :58322 (extension, 15 tools)

• Using only Mermaid-based diagram tools? Install staruml-mcp only. The 4 built-in tools work.
• Want the full 19 tools (project save/open, element CRUD, execute any StarUML command)? Install both.

Prerequisites

• StarUML v7.0.0+ with API Server enabled (see below)
• Node.js 20+ on the machine running the AI agent
• (Optional) staruml-mcp-extension installed in StarUML — required for 15 of the 19 tools

Enable StarUML API Server

Edit settings.json at:

• Windows: %APPDATA%\StarUML\settings.json
• macOS: ~/Library/Application Support/StarUML/settings.json
• Linux: ~/.config/StarUML/settings.json

Add or update:

{

"apiServer": true, "apiServerPort": 58321 }

Restart StarUML.

Verify:

curl http://localhost:58321/

→ "Hello from StarUML API Server!"

Install & Use

Claude Code (recommended — HTTP transport)

Start the server in a terminal:

npx -y staruml-mcp --transport http

listens on http://localhost:58323/mcp by default

Register with Claude Code:

claude mcp add --transport http staruml http://localhost:58323/mcp

Port `58323` is the canonical HTTP port, chosen to sit alongside StarUML's built-in API (58321) and staruml-mcp-extension (58322). Override with --port if needed.

Restart Claude Code. Ask:

"What StarUML tools do you have?"

Claude Desktop (stdio transport)

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{

"mcpServers": { "staruml": { "command": "npx", "args": ["-y", "staruml-mcp"] } } }

Restart Claude Desktop.

Cursor / VS Code Copilot / Codex CLI

Point your MCP client at npx -y staruml-mcp (stdio) or http://localhost:58323/mcp (HTTP).

CLI

staruml-mcp [options]

-t, --transport stdio | http (default: stdio) -p, --port HTTP listen port (default: 58323) --api-port StarUML built-in API port (default: 58321) --ext-port staruml-mcp-extension port(default: 58322) --api-host StarUML API host prefix (default: http://localhost) -V, --version Print version -h, --help Show help

Tools Exposed

Built-in (always available, port 58321)

Extension tools (require staruml-mcp-extension, port 58322)

To enable extension tools: install staruml-mcp-extension in StarUML (Tools → Extension Manager → Install From URL → https://github.com/ezrabrilliant/staruml-mcp-extension).

Example Prompts

• *"Create an ER diagram in StarUML for a POS database: users, menus, transactions with relationships."*
• *"Generate a sequence diagram for JWT login: frontend → /api/auth/login → AuthService → DB → JWT response."*
• *"Show me the current diagram in StarUML."*
• *"Export diagram with ID xyz123 as an image."*

Development

git clone https://github.com/ezrabrilliant/staruml-mcp.git

cd staruml-mcp npm install npm run dev # tsx watch on src/ npm run build # bundle to dist/ npm test # vitest npm run typecheck # tsc --noEmit

Architecture

AI Agent (Claude Code / Cursor / VS Code / …)

│ │ MCP (stdio or Streamable HTTP) ▼ staruml-mcp (this package) │ │ HTTP JSON-RPC ▼ StarUML API Server (port 58321) │ ▼ StarUML Application (v7+)

Acknowledgments

Inspired by staruml/staruml-mcp-server (official stdio-only server by Minkyu Lee, StarUML creator). This project reimplements it with multi-transport support and strict TypeScript.

License

MIT © Ezra Brilliant Konterliem