MCP ArchiMate Server

A Model Context Protocol (MCP) server for ArchiMate/CoArchi model interaction. Works with VS Code Copilot, Cursor, and other MCP-compatible clients.

Overview

MCP ArchiMate Server enables AI assistants to read and write ArchiMate models stored in CoArchi XML format. Query elements, create relationships, design diagrams, and sync changes to Git—all through natural language.

Repository: https://github.com/dqxorg/mcp-archimate

Features

• Read and search ArchiMate models (CoArchi XML format)
• Create elements, relationships, and diagrams
• Generate models from architecture documentation
• Auto-add visual connections to diagrams
• Commit and push changes to Git branches
• Full ArchiMate 3.2 schema support

Installation

Quick Install (Node.js - Recommended)

1. Install via npm:

npm install -g archimate-chloe-mcp

2. Add to VS Code settings (Ctrl+, → click {} icon):

{
  "mcp": {
    "servers": {
      "archimate": {
        "command": "archimate-chloe-mcp",
        "env": {
          "ARCHIMATE_MODEL_PATH": "/path/to/your/archimate/model"
        }
      }
    }
  }
}

3. Restart VS Code

Alternative: MCP CLI

mcp add archimate -- archimate-chloe-mcp

Alternative: Clone from GitHub

git clone https://github.com/dqxorg/mcp-archimate.git
cd mcp-archimate
npm install

Then add to VS Code settings:

{
  "mcp": {
    "servers": {
      "archimate": {
        "command": "node",
        "args": ["/path/to/mcp-archimate/server.js"],
        "env": {
          "ARCHIMATE_MODEL_PATH": "/path/to/your/archimate/model"
        }
      }
    }
  }
}

Configuration

Set the ARCHIMATE_MODEL_PATH environment variable to your CoArchi model directory:

# Linux/Mac
export ARCHIMATE_MODEL_PATH=~/Documents/Archi/models/my-architecture

# Windows
set ARCHIMATE_MODEL_PATH=C:\Users\chloe\Documents\Archi\models\my-architecture

Running the Server

Python

python -m archimate_mcp.server

Node.js

node server.js

VS Code Copilot Setup

After installation, use the archimate-chloe-mcp command:

{
  "mcp": {
    "servers": {
      "archimate": {
        "command": "archimate-chloe-mcp",
        "env": {
          "ARCHIMATE_MODEL_PATH": "/path/to/your/archimate/model"
        }
      }
    }
  }
}

Set ARCHIMATE_MODEL_PATH to your CoArchi model folder (the one with model/business/, model/application/, etc.).

Restart VS Code after adding the configuration.

Verify Setup

Ask Copilot:

• "What's in my application layer?"
• "Show me all elements"

If you get a response, the MCP server is connected.

Available Tools

Model Operations

| Tool | Description | |------|-------------| | get_model_summary | Get model statistics by layer and type | | list_elements_by_layer | List elements in business/application/technology layer | | search_elements | Search elements by name | | get_element | Get element details by ID | | validate_model | Check model for errors |

Model Modification

| Tool | Description | |------|-------------| | create_element | Create a new element | | create_relationship | Create a relationship between elements | | create_diagram | Create a new diagram/view | | add_element_to_diagram | Add element to existing diagram | | add_connection_to_diagram | Add visual connection line | | add_connections_from_relationships | Auto-add all connections | | design_from_document | Generate model from markdown | | commit_and_push | Git commit and push |

Schema Discovery

| Tool | Description | |------|-------------| | list_available_element_types | List all ArchiMate element types | | list_relationship_types | List all relationship types |

Usage Examples

User: What's in my application layer?
→ Returns all application components and functions

User: Show me the API component
→ Returns element details with relationships

User: Create a BusinessActor for Product Owner
→ Creates new element in business layer

User: Connect the API to the Database with AccessRelationship
→ Creates relationship between elements

User: Add all connections to the C1 diagram
→ Adds visual connection lines for all relationships

User: Design from C:/docs/architecture.md
→ Generates full model from markdown document

ArchiMate Element Types

Business Layer

BusinessActor, BusinessRole, BusinessCollaboration, BusinessProcess, BusinessFunction, BusinessService, BusinessObject

Application Layer

ApplicationComponent, ApplicationFunction, ApplicationService, DataObject

Technology Layer

Node, Device, SystemSoftware, TechnologyService, Artifact

Relationship Types

| Type | Use Case | |------|----------| | ServingRelationship | Service provided to actor | | FlowRelationship | Data/control flow | | AccessRelationship | Read/write data | | AssignmentRelationship | Actor assigned to element | | RealizationRelationship | Implementation of specification | | CompositionRelationship | Strong whole-part | | AggregationRelationship | Whole-part | | TriggeringRelationship | Event trigger |

Model Structure

The server expects a CoArchi model structure:

model-repository/
└── your-model/
    └── model/
        ├── business/          # Business layer elements
        ├── application/       # Application layer elements
        ├── technology/        # Technology layer elements
        ├── relations/         # All relationships
        └── diagrams/          # Views and diagrams

Git Integration

The commit_and_push tool automatically:

1. Stages all changes
2. Commits with your message
3. Creates a new branch (archi/{user}-{date})
4. Pushes to origin

Troubleshooting

Model not loading?

• Verify ARCHIMATE_MODEL_PATH is set correctly
• Check model has proper folder structure (model/business/, model/application/, etc.)

Connections not visible in diagram?

• Use add_connections_from_relationships tool
• Press F5 in CoArchi to reload

Element not found?

• Use search_elements to find the correct ID
• Check if element exists in the model

License

MIT

Add to your VS Code settings (settings.json):

{
  "mcpServers": {
    "archimate": {
      "command": "python",
      "args": ["-m", "archimate_mcp.server"],
      "env": {
        "ARCHIMATE_MODEL_PATH": "C:\\path\\to\\your\\archimate\\model"
      }
    }
  }
}

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "archimate": {
      "command": "python",
      "args": ["-m", "archimate_mcp.server"],
      "env": {
        "ARCHIMATE_MODEL_PATH": "/path/to/your/archimate/model"
      }
    }
  }
}

Development

# Create virtual environment
python -m venv .venv

# Activate
source .venv/Scripts/activate  # Linux/Mac
.venv\Scripts\activate        # Windows

# Install dependencies
pip install fastmcp

# Run tests
python -c "import sys; sys.path.insert(0, '.'); from archimate_mcp.server import get_model; m = get_model(); print(m.get_summary())"

License

MIT License

Repository

https://github.com/dqxorg/mcp-archimate