Astah Pro MCP: Enabling AI-Powered UML Modeling

A local MCP server plugin for Astah Professional, a UML modeling tool, that enables AI agents to:

  • Design systems and represent them as UML models.
  • Explain UML models.
  • Generate source code from UML models, and vice versa.
  • Create UML diagrams from hand-drawn sketches.

These videos show Claude Code (Opus 4.8) designing a simple library management system and drawing diagrams. They are played at 20× speed.

Prompt: Design a simple library management system and draw a class diagram in Astah to illustrate its structure.
class-diagram.gif

Prompt: Based on the contents of the Astah model, draw a sequence diagram to illustrate the behavior of borrowing a book.
sequence-diagram.gif

Prompt: Based on the contents of the Astah model, draw an activity diagram to illustrate the behavior of returning a book.
activity-diagram.gif

Prompt: Based on the contents of the Astah model, draw a state machine diagram to illustrate the state transitions of a book.
state-machine-diagram.gif

Diagrams created in the videos above: The diagram layouts were manually adjusted.

Requirements

  • Astah Pro v12.0 or later

  • AI agents

    • For the full (query + edit) tool version:

      With over 300 tools exposed in this version, use the AI agents listed below. Other AI agents may fail to connect due to the large number of tools, or may connect but only recognize a subset.

      • Claude Code
      • Codex CLI
      • Grok Build
      • Antigravity CLI

    • For the query-only tool version:

      This version exposes around 125 tools, so many AI agents will likely be able to use it. Note that the AI agent can only reference information about model elements and diagrams.

    Note: This MCP server only connects to AI agents running on the same machine as Astah Professional. According to Astah's terms of use, using Astah via an AI agent is permitted only if you hold a valid license and access it exclusively for your own use with your licensed Astah. Allowing a non-licensed third party to operate Astah via such an agent is strictly prohibited.
    For details, please refer to the FAQ (English / Japanese) or contact Change Vision (the developer of Astah) directly.

Supported Diagram Types

This MCP server can view and edit the following diagrams:

  • Class Diagram
  • Sequence Diagram
  • Activity Diagram
  • State Machine Diagram
  • Usecase Diagram
  • Mind Map
  • Requirement Diagram
  • Communication Diagram (query-only)
  • Composite Structure Diagram (query-only)
  • ER Diagram (query-only)

Installation

Install Astah Pro

Download from here and install.

Install the Astah Pro MCP plugin

Download the plugin JAR file (astah-pro-mcp-x.x.x.jar), drop it into Astah, and restart Astah (see here). If the mcp tab appears in the Extensions view, the plugin is installed.

mcp tab

AI agent settings

To use the full tool version, specify port 8888; to use the query-only tool version, specify port 8889. Also, use 127.0.0.1 not localhost. Connections to localhost will fail.

Claude Code

Run this command for project scope in your project directory:

claude mcp add --transport http --scope project astah-pro-mcp http://127.0.0.1:8888/mcp

Or run this command for user scope:

claude mcp add --transport http --scope user astah-pro-mcp http://127.0.0.1:8888/mcp

Codex CLI

Create .codex/config.toml under your project directory or your user directory with:

[mcp_servers.astah-pro-mcp]
transport = "http"
url = "http://127.0.0.1:8888/mcp"
startup_timeout_sec = 10

Grok Build

Run this command for project scope in your project directory:

grok mcp add --scope project --transport http astah-pro-mcp http://127.0.0.1:8888/mcp

Or run this command for user scope:

grok mcp add --scope user --transport http astah-pro-mcp http://127.0.0.1:8888/mcp

Antigravity CLI

Create .agents/mcp_config.json under your project directory, or create ~/.gemini/antigravity-cli/mcp_config.json for user scope.

{
  "mcpServers": {
    "astah-pro-mcp": {
      "serverUrl": "http://127.0.0.1:8888/mcp"
    }
  }
}

How to Use

  1. Start Astah Pro

    Some AI agents try to connect to the MCP server on startup, so start Astah Pro first.

  2. Start AI agents

    On the first connection to the Astah Pro MCP server, you will be asked to confirm. Review the details and click 'Connect'.
    Connection Request

  3. Send prompts to the AI agents

If you want to disable the Astah Pro MCP plugin in Astah, click [Plugin] > [Installed Plugin], select the Astah Pro MCP entry in the plugin list dialog, click Disable, and then restart Astah.

Build & Test

If you want to build and test locally:

  1. Set up your Astah plugin development environment (see here).

  2. Build:

    astah-build

  3. Run tests (change astahPath to your Astah Pro installation path):

    Run all tests on Windows 11:

    astah-mvn test -DastahPath="C:\Program Files\astah-professional"

    Run specific tests on Windows 11:

    astah-mvn test -DastahPath="C:\Program Files\astah-professional" -Dtest="**/editor/*Test"

Considerations

Experimental Status

This project is currently experimental. The design and implementation may undergo breaking changes.

Confidential Risk

Astah project data and logs will be shared with the AI agent. For Astah projects that contain confidential information, either refrain from using this MCP server or use it only with appropriate safeguards (e.g., enabling opt-out settings for AI agents).

Backups Recommended

Because this MCP server edits model elements and diagrams, we recommend committing your Astah project to a Git repository or making copies before and during use so you can revert if necessary.

Feature Limitations

Some model or diagram information (e.g., certain properties) cannot be viewed or edited via the provided tool functions. Use the Astah GUI directly for those.

Costs

This MCP server prioritizes providing the information AI agents need and does not implement token-saving measures. We recommend using AI agents on a flat-rate plan rather than pay-as-you-go.

AI Limitations

As with source code, AI agents can make mistakes or misinterpret model elements and diagrams.

License

Some tool functions provided by this MCP server return excerpts from the OMG UML 2.5.1, OMG SysML 1.7 specifications, and FIPS PUB 184 IDEF1X. The OMG UML/SysML specifications are licensed as stated at the beginning of each document. FIPS PUB 184 IDEF1X is a U.S. Government work (NIST) and is not subject to copyright protection in the United States (17 U.S.C. §105), but may be subject to foreign copyright. When content from these specifications/documents is returned by tool functions, it is explicitly indicated as an excerpt. "Mind Map" is a registered trademark of The Buzan Organisation Limited.

All other works, including source code, are copyrighted by Takaaki Teshima and released under the MIT-0 license.
License: MIT-0

Disclaimer

This project is developed independently by the authors in their personal capacities and is not affiliated with any university, institution, or employer.

Got a feature request or found a bug?

Please open an issue. Because this project is experimental phase and may introduce breaking changes, we aren't accepting pull requests until the design and implementation stabilize. Thank you for your understanding.

Need support?

If you need private support, contact takaaki.teshima.dev [at] gmail.com (replace [at] with @). It could become a paid project; I may still be able to support you/it.