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