Use AI Clients with Real UML Models: Astah’s MCP server
Astah includes a built-in MCP server that lets AI clients such as Claude Code, Claude Desktop, GitHub Copilot and Codex work directly with your UML models. Instead of generating a diagram image, the AI reads the model in Astah, makes changes, and leaves you with a model you can keep editing. The MCP server is included in Astah Professional, Astah UML, Astah SysML and Astah System Safety version 11 and later, with no separate installation.
What is MCP?
MCP (Model Context Protocol) is an open standard for connecting AI clients to tools and applications. An MCP server exposes what a tool can do, and any MCP-compatible AI client can use it. Astah’s MCP server runs on your own computer while Astah is open, and AI clients connect to it locally.
Two kinds of MCP tools for UML: diagram generators and modeling tools
If you search for “UML MCP server”, you will find two different kinds of tools. Both are useful, but they solve different problems.
| Diagram generators (PlantUML or Mermaid based) | Modeling tools with an MCP server (such as Astah) | |
|---|---|---|
| What the AI produces | Diagram source text, rendered as an image | Elements and diagrams in a real model |
| Consistency across diagrams | Each diagram stands alone. Renaming a class in one diagram does not change the others | One model. A class renamed once is renamed in every diagram that shows it |
| Round-trip editing | Mostly one-way: generate, then regenerate | Read the model, change it, save it, and continue editing by hand or with AI |
| Hand editing after AI | Edit the text source | Edit visually in Astah, with the model kept consistent |
| Best for | Quick diagrams in documents, wikis and pull requests | Designs you will maintain, review and extend over time |
| Setup | Usually nothing to install | Astah must be running on your computer |
In short, a diagram generator is the lighter choice when you only need a picture in a document. When the diagrams are part of a design you will keep working on, an MCP server that works on the model itself avoids the drift that comes from regenerating separate images.
What you can do with Astah’s MCP server
- Create diagrams from requirements or specifications. Give the AI client a document and ask it to draft class, use case or sequence diagrams as a model in Astah.
- Update an existing model. Ask the AI to add attributes, rename elements, or restructure relationships. The changes apply across all diagrams.
- Analyze a model. Ask questions about the model, such as which classes depend on a given class, or what is missing from a use case diagram.
- Connect modeling with code and documents. Use the same AI client that works with your code and documentation to keep the model in step with them.
For step-by-step scenarios and prompt examples, see Detailed Scenarios & Prompt Examples. The scenarios currently cover Astah Professional and Astah UML.
How it works
- You turn on MCP Integration in Astah’s AI Chat Copilot settings and choose a port (the default is 3099).
- You register Astah’s MCP server in your AI client, using the endpoint
http://localhost:3099/mcp. - The AI client calls Astah’s MCP server to read and change the model open in Astah.
To use Astah’s MCP server, you need your own API key from a supported AI service, such as OpenAI, Claude or Gemini, entered in Astah’s AI Chat Copilot settings. Usage of the AI service is billed by the AI provider.
Supported AI clients
The following MCP clients have been verified with Astah. Other MCP-compatible clients can also connect using the endpoint above.
| AI client | How to connect |
|---|---|
| Claude Code (VS Code) | One command: claude mcp add --transport http --scope user astah-mcp http://localhost:3099/mcp |
| GitHub Copilot Chat (VS Code) | Add the server in VS Code’s MCP settings |
| Cline (VS Code) | Add the server in Cline’s MCP settings |
| Copilot CLI | Add the server with the /mcp add command |
| Codex | Add the server with codex mcp add |
| Claude Desktop | Add the server to the configuration file. Requires Node.js |
For the exact settings for each client, see Connect Astah to external AI clients.
What Astah’s MCP server does not do
- It is not a cloud service. The MCP server runs on your computer, and Astah must be open while the AI client uses it. There is no real-time co-editing between team members.
- It does not replace review. AI-generated changes may be incomplete or inaccurate. Review diagrams before you rely on them.
- It does not handle unlimited model size in one request. AI services limit how much text they can process at once. Very large specifications or models may reduce quality or cause errors, so work in smaller steps.
- It does not keep your data out of the AI service. Model content you ask the AI to work with is sent to the AI service your client uses. Follow your organization’s policy on confidential information.
- It does not add simulation. Astah SysML and Astah System Safety do not include simulation, and Astah SysML supports SysML v1. For SysML v2, Change Vision offers the separate SysMLv2 Editor.
Official MCP server and community plugins
The MCP server described on this page is the official one from Change Vision, included in Astah version 11 and later. A separate community plugin, Astah Pro MCP, is developed and maintained by an Astah user, not by Change Vision.
Frequently asked questions
Do I need to install anything to use Astah’s MCP server?
No. The MCP server is included in Astah version 11 and later. You turn it on in Astah’s settings and register it in your AI client. Claude Desktop also needs Node.js.
Do I need an API key?
Yes. Astah’s MCP integration requires your own API key from a supported AI service, such as OpenAI, Claude or Gemini (or an OpenAI-compatible service). You enter it in Astah’s AI Chat Copilot settings, and usage is billed by the AI provider.
Which Astah products include the MCP server?
Astah Professional, Astah UML, Astah SysML and Astah System Safety, version 11 and later.
Can the AI change my existing models?
Yes. The AI can add, rename and restructure model elements, and the changes apply across all diagrams. Because the MCP server can modify your models, save backups or use version control.
How is this different from PlantUML or Mermaid MCP servers?
Those servers generate diagram source and images. Astah’s MCP server works on a real model, so diagrams stay consistent and you can keep editing them by hand or with AI.
Can I try it for free?
Yes. Astah offers a 20-day free trial (40 days for Astah System Safety), and students can use Astah UML free of charge.