ArchiMate

You can run ArchiMate MCP Server to generate comprehensive ArchiMate diagrams in PlantUML format, with automatic validation, layout control, and a live HTTP viewer. This server focuses on ArchiMate 3.2, supports all seven layers, and exports multiple diagram formats for easy sharing and review.

How to use

To use ArchiMate MCP Server, you connect via an MCP client and issue diagram requests. You can generate diagrams that cover all ArchiMate layers, obtain PlantUML source, PNG, SVG, and XML outputs, and view diagrams instantly through a built-in HTTP server. You can customize layout direction, spacing, grouping, and whether to include titles, legends, and enhanced relationship labels. If you enable language auto-detection, labels can adapt to Slovak or English as content demands.

How to install

Prerequisites: you need a working Python environment and the MCP client tooling that runs the server locally.

# Clone the repository
git clone https://github.com/entira/archi-mcp.git
cd archi-mcp

# Install dependencies with uv
uv sync

# Download PlantUML JAR (required for diagram generation)
curl -L https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar -o plantuml.jar

Upgrade to latest version

Keep your local server up to date by pulling the latest changes and syncing dependencies.

# Navigate to your archi-mcp directory
cd archi-mcp

# Fetch latest changes
git fetch origin

# Upgrade to specific version (e.g., v1.0.2)
git checkout v1.0.2

# Or upgrade to latest main branch
git checkout main
git pull origin main

# Update dependencies
uv sync

# Download latest PlantUML JAR if needed
curl -L https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar -o plantuml.jar

Concrete local runtime configuration

A local runtime can be started using a CLI tool through a configuration that points to the ArchiMate MCP Server module. The example below shows how to configure the runtime for local execution and parameter handling.

{
  "mcpServers": {
    "archi_mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/your/archi-mcp", "python", "-m", "archi_mcp.server"],
      "cwd": "/path/to/your/archi-mcp",
      "env": {
        "ARCHI_MCP_LOG_LEVEL": "INFO",
        "ARCHI_MCP_STRICT_VALIDATION": "true",
        "ARCHI_MCP_LANGUAGE": "auto",
        "ARCHI_MCP_DEFAULT_DIRECTION": "top-bottom",
        "ARCHI_MCP_DEFAULT_SPACING": "comfortable",
        "ARCHI_MCP_DEFAULT_TITLE": "true",
        "ARCHI_MCP_DEFAULT_LEGEND": "false",
        "ARCHI_MCP_DEFAULT_GROUP_BY_LAYER": "false",
        "ARCHI_MCP_DEFAULT_SHOW_RELATIONSHIP_LABELS": "true",
        "ARCHI_MCP_LOCK_DIRECTION": "false",
        "ARCHI_MCP_LOCK_SPACING": "false",
        "ARCHI_MCP_LOCK_TITLE": "false",
        "ARCHI_MCP_LOCK_LEGEND": "false",
        "ARCHI_MCP_LOCK_GROUP_BY_LAYER": "false",
        "ARCHI_MCP_LOCK_SHOW_RELATIONSHIP_LABELS": "false"
      }
    }
  }
}

Environment and defaults you can customize

Configure core behavior, language, layout defaults, and HTTP viewing. You can tune logging, strict validation, language labels, and visual defaults to align with your workflows.

Core configuration keys you may set include logging level, strict validation, language, default layout direction and spacing, and whether to show a title or legend. You can also lock certain parameters to prevent client overrides and enable experimental XML export adjustments.

HTTP viewing is provided on a designated host and port to instantly preview generated diagrams. Example defaults are port 8080 and host localhost.

Example workflow with a simple diagram

Create a straightforward service-oriented diagram involving a customer-facing service, an application service, and a supporting technology node. The server will produce a complete set of outputs and expose an HTTP URL for immediate viewing.

# Example usage flow (conceptual, not a full CLI integration)
# Start the local MCP server via the configured runtime (see above)
# Issue a request to generate a diagram with the desired elements
# Access the live diagram at http://localhost:8080/diagram.png

Available tools

create_archimate_diagram

Generate complete ArchiMate diagrams from structured input with support for all 55+ element types across 7 layers, all 12 ArchiMate relationship types, multi-format export (PlantUML, PNG, SVG, ArchiMate XML), built-in HTTP server, and layout customization with multi-language support.

test_element_normalization

Test element type normalization across all ArchiMate layers, validating case-insensitive input handling and common element mappings.