StarUML MCP Server

StarUML is a sophisticated modeler for agile and concise modeling. StarUML MCP Server is a Model Context Protocol 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.

Related MCP server: PlantUML MCP Server

Requirements

• StarUML v7.0.0 or higher (v8.1.0 or higher for execute_script)

• Node.js v22 or higher

Use the version of StarUML MCP Server matching your StarUML:

Setup

Claude Desktop

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

{
  "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

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.

{
  "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

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:

// 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.

{
  "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 by npm run inspect (after building).