# StarUML MCP Server

[StarUML](https://staruml.io) is a sophisticated modeler for agile and concise modeling. **StarUML MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants such as Claude work with StarUML: create diagrams from prompts, read the diagrams in the current project, see diagram images, and query or modify models with scripts (e.g. generate code from diagrams).

## How It Works

StarUML runs a local API server (`http://127.0.0.1:58321` by default). StarUML MCP Server is a small Node.js program that the AI client runs over stdio, and it translates each MCP tool call to a request to the StarUML API server.

```
AI client (Claude Desktop, Claude Code, ...) ──stdio──▶ StarUML MCP Server ──HTTP──▶ StarUML (API server)
```

StarUML must be running with a project open while you use the tools.

## Requirements

- [StarUML](https://staruml.io/) `v7.0.0` or higher (`v8.1.0` or higher for `execute_script`)
- [Node.js](https://nodejs.org/) `v22` or higher

Use the version of StarUML MCP Server matching your StarUML:

| StarUML | StarUML MCP Server |
| ------- | ------------------ |
| `v8`    | `0.3.x` (latest)   |
| `v7`    | `0.1.0`            |

## Setup

### Claude Desktop

Add the server to `claude_desktop_config.json` (**Settings > Developer > Edit Config**) and restart Claude Desktop:

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

For StarUML `v7`, use `staruml-mcp-server@0.1.0` instead of `staruml-mcp-server`.

### Claude Code

```bash
claude mcp add staruml -- npx -y staruml-mcp-server
```

### Other MCP Clients

Any MCP client that supports stdio servers can run the server with the command `npx -y staruml-mcp-server`.

### Options

- `--api-port=<port>`: Port of the StarUML API server (default: `58321`). Use it when you change the port in StarUML.

```json
{
  "mcpServers": {
    "staruml-mcp-server": {
      "command": "npx",
      "args": ["-y", "staruml-mcp-server", "--api-port=60000"]
    }
  }
}
```

## StarUML Settings

In StarUML `v8.1.0` or higher, the API server is configured in **Preferences > API Server** (restart StarUML after changing them):

- **Run on Start**: Run the API server when StarUML starts (default: on).
- **Port**: Port number of the API server (default: `58321`). If you change it, pass the same port with `--api-port`.

The API server listens on the loopback address (`127.0.0.1`) only, so it cannot be reached from other machines.

## API Access

With StarUML `v8`, when the MCP server calls StarUML for the first time, StarUML asks you to allow API access for "StarUML MCP Server". Click **Allow** to continue. The access is kept until StarUML is restarted, and StarUML asks again after a restart (the MCP server requests a new access automatically).

StarUML `v7` does not ask for API access.

## Tools

| Tool                       | Description                                                                                                                                                                                                                                                                 |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `generate_diagram`         | Generate a diagram from [Mermaid](https://mermaid.js.org) code. Supported diagrams: `classDiagram`, `sequenceDiagram`, `flowchart`, `erDiagram`, `mindmap`, `requirementDiagram`, `stateDiagram`.                                                                           |
| `get_all_diagrams_info`    | Get the ID, type, name and description of all diagrams in the project.                                                                                                                                                                                                      |
| `get_current_diagram_info` | Get the ID, type, name and description of the diagram currently open in the editor.                                                                                                                                                                                         |
| `get_diagram_image_by_id`  | Get a PNG image of a diagram by its ID (from `get_all_diagrams_info` or `get_current_diagram_info`), so the AI can see the diagram.                                                                                                                                         |
| `execute_script`           | Execute JavaScript code with the [Scripting API](https://docs.staruml.io/developing-extensions/scripting-api/) in StarUML and get the result of the evaluation and the console outputs (StarUML `v8.1.0` or higher). The AI can read models, modify them, and run commands. |

### `execute_script`

The code runs in the same environment as the **Script Console** of StarUML (QuickJS):

- Globals: `app` (`app.repository`, `app.project`, `app.engine`, `app.factory`, `app.commands`, `app.selections`, `app.diagrams`, `app.dialogs`, `app.toast`, `app.preferences`, `app.metamodels`, ...), `type` (element classes such as `type.UMLClass`) and `console`.
- The value of the last expression is returned as text. Console outputs (`console.log`, ...) are returned too.
- Global variables are kept between executions.
- Top-level `await`, `require()`, timers, Node.js APIs and file access are not available.
- Changes made with `app.engine`, `app.factory` or an `OperationBuilder` can be undone in StarUML (**Edit > Undo**).

For example:

```js
// names of all classes
app.repository.select("@UMLClass").map((c) => c.name);

// add a `createdAt` attribute to all classes
app.repository.select("@UMLClass").forEach((c) => {
  app.factory.createModel({
    id: "UMLAttribute",
    parent: c,
    field: "attributes",
    modelInitializer: (a) => {
      a.name = "createdAt";
      a.type = "Date";
    },
  });
});
```

Since scripts can change your models, review what the AI is going to run when your client asks for approval of the tool call.

## Example Prompts

- _"Create a class diagram for book store in StarUML"_
- _"Create a sequence diagram for OAuth authentication in StarUML"_
- _"Explain the current diagram in StarUML"_
- _"Review the class diagrams in StarUML and suggest improvements"_
- _"Generate SQL DDL from the current ERD diagram in StarUML"_
- _"Generate TypeScript interfaces from the classes in StarUML"_
- _"Add a `createdAt` attribute to all classes in StarUML"_
- _"Find classes without documentation in StarUML"_

## Troubleshooting

- **Connection refused (`ECONNREFUSED`)**: StarUML is not running, or the API server is off or uses another port. Check **Preferences > API Server** in StarUML and the `--api-port` option.
- **401 errors with StarUML `v8`**: An older version of StarUML MCP Server may be cached by npx. Use `staruml-mcp-server@latest` once or clear `~/.npm/_npx`.
- **"User denied API access"**: You clicked **Deny** in the dialog of StarUML. Call the tool again and click **Allow**.
- **`execute_script` fails**: `execute_script` needs StarUML `v8.1.0` or higher. Update StarUML.

## Dev

1. Clone this repository.
2. Install dependencies with `npm install`.
3. Build with `npm run build`.
4. Update `claude_desktop_config.json` in Claude Desktop as below.
5. Restart Claude Desktop.

```json
{
  "mcpServers": {
    "staruml-mcp-server": {
      "command": "node",
      "args": ["<full-path-to>/staruml-mcp-server/build/index.js"]
    }
  }
}
```

You can also test the tools with [MCP Inspector](https://github.com/modelcontextprotocol/inspector) by `npm run inspect` (after building).