{
  "markdown": "# staruml-mcp\n\n[![npm version](https://img.shields.io/npm/v/staruml-mcp.svg)](https://www.npmjs.com/package/staruml-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/staruml-mcp.svg)](https://www.npmjs.com/package/staruml-mcp)\n[![CI](https://github.com/ezrabrilliant/staruml-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ezrabrilliant/staruml-mcp/actions/workflows/ci.yml)\n[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io/)\n\nModel Context Protocol (MCP) server for [StarUML](https://staruml.io). 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.\n\n## How it fits together\n\n```\n  AI Agent  ──MCP──►  staruml-mcp (this package)  ──HTTP──►  StarUML\n                                                  :58321 (built-in, 4 tools)\n                                                  :58322 (extension, 15 tools)\n```\n\n| Package | What it is | Where it runs |\n|---|---|---|\n| **`staruml-mcp`** (this repo) | MCP server for AI agents | your machine via `npx -y staruml-mcp` |\n| **[`staruml-mcp-extension`](https://github.com/ezrabrilliant/staruml-mcp-extension)** | StarUML plugin adding 15 HTTP endpoints | inside StarUML (install once via Extension Manager) |\n\n- Using only Mermaid-based diagram tools? Install `staruml-mcp` only. The 4 built-in tools work.\n- Want the full 19 tools (project save/open, element CRUD, execute any StarUML command)? Install **both**.\n\n## Prerequisites\n\n- **StarUML v7.0.0+** with API Server enabled (see below)\n- **Node.js 20+** on the machine running the AI agent\n- **(Optional)** [`staruml-mcp-extension`](https://github.com/ezrabrilliant/staruml-mcp-extension) installed in StarUML — required for 15 of the 19 tools\n\n### Enable StarUML API Server\n\nEdit `settings.json` at:\n- **Windows:** `%APPDATA%\\StarUML\\settings.json`\n- **macOS:** `~/Library/Application Support/StarUML/settings.json`\n- **Linux:** `~/.config/StarUML/settings.json`\n\nAdd or update:\n```json\n{\n  \"apiServer\": true,\n  \"apiServerPort\": 58321\n}\n```\n\nRestart StarUML.\n\nVerify:\n```bash\ncurl http://localhost:58321/\n# → \"Hello from StarUML API Server!\"\n```\n\n## Install & Use\n\n### Claude Code (recommended — HTTP transport)\n\nStart the server in a terminal:\n```bash\nnpx -y staruml-mcp --transport http\n# listens on http://localhost:58323/mcp by default\n```\n\nRegister with Claude Code:\n```bash\nclaude mcp add --transport http staruml http://localhost:58323/mcp\n```\n\n> **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 <n>` if needed.\n\nRestart Claude Code. Ask:\n> \"What StarUML tools do you have?\"\n\n### Claude Desktop (stdio transport)\n\nEdit `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"staruml\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"staruml-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop.\n\n### Cursor / VS Code Copilot / Codex CLI\n\nPoint your MCP client at `npx -y staruml-mcp` (stdio) or `http://localhost:58323/mcp` (HTTP).\n\n## CLI\n\n```\nstaruml-mcp [options]\n\n  -t, --transport <type>   stdio | http              (default: stdio)\n  -p, --port <number>      HTTP listen port          (default: 58323)\n      --api-port <number>  StarUML built-in API port (default: 58321)\n      --ext-port <number>  staruml-mcp-extension port(default: 58322)\n      --api-host <url>     StarUML API host prefix   (default: http://localhost)\n  -V, --version            Print version\n  -h, --help               Show help\n```\n\n## Tools Exposed\n\n### Built-in (always available, port 58321)\n\n| Tool | Description |\n|---|---|\n| `generate_diagram` | Generate a UML diagram from Mermaid code. |\n| `get_all_diagrams_info` | List all diagrams in the current project (id, name, type). |\n| `get_current_diagram_info` | Get metadata of the currently focused diagram. |\n| `get_diagram_image_by_id` | Export a diagram as PNG by its ID. |\n\n### Extension tools (require [`staruml-mcp-extension`](https://github.com/ezrabrilliant/staruml-mcp-extension), port 58322)\n\n| Tool | Description |\n|---|---|\n| `get_all_commands` | List all 138+ built-in StarUML command IDs. |\n| `execute_command` | Execute any built-in command (e.g. `project:save`, `view:fit-to-window`). |\n| `get_project_info` | Current project's filename + top-level elements. |\n| `save_project` / `save_project_as` / `new_project` / `open_project` | Project file lifecycle. |\n| `get_element_by_id` / `find_elements` | Query model elements. |\n| `create_element` / `update_element` / `delete_element` | Element CRUD. |\n| `create_diagram` (typed native) / `switch_diagram` / `close_diagram` | Diagram management. |\n\nTo enable extension tools: install `staruml-mcp-extension` in StarUML (Tools → Extension Manager → Install From URL → `https://github.com/ezrabrilliant/staruml-mcp-extension`).\n\n## Example Prompts\n\n- *\"Create an ER diagram in StarUML for a POS database: users, menus, transactions with relationships.\"*\n- *\"Generate a sequence diagram for JWT login: frontend → /api/auth/login → AuthService → DB → JWT response.\"*\n- *\"Show me the current diagram in StarUML.\"*\n- *\"Export diagram with ID `xyz123` as an image.\"*\n\n## Development\n\n```bash\ngit clone https://github.com/ezrabrilliant/staruml-mcp.git\ncd staruml-mcp\nnpm install\nnpm run dev          # tsx watch on src/\nnpm run build        # bundle to dist/\nnpm test             # vitest\nnpm run typecheck    # tsc --noEmit\n```\n\n## Architecture\n\n```\nAI Agent (Claude Code / Cursor / VS Code / …)\n        │\n        │  MCP (stdio or Streamable HTTP)\n        ▼\n  staruml-mcp  (this package)\n        │\n        │  HTTP JSON-RPC\n        ▼\nStarUML API Server (port 58321)\n        │\n        ▼\n  StarUML Application (v7+)\n```\n\n## Acknowledgments\n\nInspired by [`staruml/staruml-mcp-server`](https://github.com/staruml/staruml-mcp-server) (official stdio-only server by Minkyu Lee, StarUML creator). This project reimplements it with multi-transport support and strict TypeScript.\n\n## License\n\n[MIT](LICENSE) © Ezra Brilliant Konterliem\n",
  "bytes": 6324,
  "sha": "5ca5e297743e09fda9683630deb5b3953079bf02c1d6901639786bd6134a8b1c",
  "repo_slug": "ezrabrilliant/staruml-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ezrabrilliant_staruml_mcp_75ae60c3/readme"
}