staruml-mcp

staruml-mcp

StarUML 用の Model Context Protocol（MCP）サーバーです。AI エージェント（Claude Code、Cursor、VS Code Copilot、Codex）から StarUML をプログラムで操作できます。Mermaid から UML 図を生成したり、組み込みコマンドを実行したり、要素を CRUD 操作したり、プロジェクトを保存したりできます。

全体の仕組み

  AI Agent  ──MCP──►  staruml-mcp (this package)  ──HTTP──►  StarUML
                                                  :58321 (built-in, 4 tools)
                                                  :58322 (extension, 15 tools)

パッケージ	内容	実行場所
staruml-mcp（このリポジトリ）	AI エージェント用の MCP サーバー	npx -y staruml-mcp を使ってお使いのマシンで実行
staruml-mcp-extension	15 個の HTTP エンドポイントを追加する StarUML プラグイン	StarUML 内（拡張機能マネージャーから一度インストール）

• Mermaid ベースの図作成ツールだけを使う場合は、staruml-mcp のみをインストールしてください。組み込みツール 4 個を利用できます。
• 19 個すべてのツール（プロジェクトの保存／オープン、要素の CRUD 操作、StarUML の任意のコマンドの実行）を使う場合は、両方をインストールしてください。

前提条件

• API Server が有効になっている StarUML v7.0.0+（以下を参照）
• AI エージェントを実行するマシンに Node.js 20+
• （任意） StarUML に staruml-mcp-extension をインストール — 19 個のツールのうち 15 個を使う場合に必要です

StarUML API Server を有効にする

次の場所にある settings.json を編集します。

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

次の内容を追加または更新します。

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

StarUML を再起動します。

確認します。

curl http://localhost:58321/
# → "Hello from StarUML API Server!"

インストールと使用方法

Claude Code（推奨 — HTTP トランスポート）

ターミナルでサーバーを起動します。

npx -y staruml-mcp --transport http
# listens on http://localhost:58323/mcp by default

Claude Code に登録します。

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

ポート 58323 は標準の HTTP ポートです。StarUML の組み込み API（58321）および staruml-mcp-extension（58322）に続く番号として選ばれています。必要に応じて --port <n> で変更できます。

Claude Code を再起動し、次のように尋ねます。

「どの StarUML ツールを使えますか？」

Claude Desktop（stdio トランスポート）

%APPDATA%\Claude\claude_desktop_config.json（Windows）または ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）を編集します。

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

Claude Desktop を再起動します。

Cursor / VS Code Copilot / Codex CLI

MCP クライアントに npx -y staruml-mcp（stdio）または http://localhost:58323/mcp（HTTP）を指定します。

CLI

staruml-mcp [options]

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

公開されるツール

組み込み（常に利用可能、ポート 58321）

ツール	説明
generate_diagram	Mermaid コードから UML 図を生成します。
get_all_diagrams_info	現在のプロジェクト内にあるすべての図の一覧を取得します（ID、名前、種類）。
get_current_diagram_info	現在フォーカスされている図のメタデータを取得します。
get_diagram_image_by_id	ID を指定して図を PNG としてエクスポートします。

拡張ツール（staruml-mcp-extension が必要です。ポート 58322）

ツール	説明
get_all_commands	組み込みの StarUML コマンド ID を 138 個以上一覧表示します。
execute_command	任意の組み込みコマンドを実行します（例：project:save、view:fit-to-window）。
get_project_info	現在のプロジェクトのファイル名と最上位の要素を取得します。
save_project / save_project_as / new_project / open_project	プロジェクトファイルのライフサイクルを管理します。
get_element_by_id / find_elements	モデル要素を検索します。
create_element / update_element / delete_element	要素の CRUD 操作を行います。
create_diagram（型指定されたネイティブ機能）/ switch_diagram / close_diagram	図を管理します。

拡張ツールを有効にするには、StarUML に staruml-mcp-extension をインストールします（Tools → Extension Manager → Install From URL → https://github.com/ezrabrilliant/staruml-mcp-extension）。

プロンプトの例

• 「StarUML で、ユーザー、メニュー、トランザクションとその関係を含む POS データベースの ER 図を作成してください。」
• 「JWT ログインのシーケンス図を生成してください：フロントエンド → /api/auth/login → AuthService → DB → JWT レスポンス。」
• 「StarUML で現在の図を表示してください。」
• 「ID xyz123 の図を画像としてエクスポートしてください。」

開発

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

アーキテクチャ

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+)

謝辞

staruml/staruml-mcp-server（StarUML の開発者である Minkyu Lee による公式の stdio 専用サーバー）に着想を得ています。このプロジェクトでは、マルチトランスポート対応と厳格な TypeScript を採用して再実装しています。

ライセンス

MIT © Ezra Brilliant Konterliem