archimate-mcp

A self-contained ArchiMate model engine exposed as a Model Context Protocol (MCP) server and an A2A agent. It gives AI agents full ArchiMate 3.x authoring capabilities — create/load/save models, full CRUD on elements, relationships, folders, and views (diagrams), query/traverse the model, and import/export the Open Group Model Exchange File Format so the models open directly in Archi.

Archi has no native server API, so archimate-mcp ships its own dependency-light engine built on the Python standard library (xml.etree.ElementTree).

Documentation — Installation, deployment, usage across the API, CLI, and MCP interfaces, and the A2A agent server are maintained in the official documentation.

Table of Contents

• Overview
• Installation
• Usage
• Architecture
• Deployment
• Environment Variables
• MCP Tools

Overview

archimate-mcp exposes a standardized interface for authoring ArchiMate models via the Model Context Protocol. The full ArchiMate vocabulary (Strategy, Business, Application, Technology, Physical, Motivation, Implementation layers) and all relationship types are supported, with structural validation and round-trip Open Exchange Format serialization.

Installation

pip install -e .

Usage

Run the MCP server directly:

archimate-mcp

Or run the agent server:

archimate-agent

Architecture

See /docs for architectural diagrams and further documentation. The model engine lives in archimate_mcp/api/ (archimate_model.py, api_client_archi.py), the MCP tools in archimate_mcp/mcp/mcp_archi.py.

Deployment

Bare-metal

archimate-agent

Docker

docker build -f docker/Dockerfile -t archimate-mcp .

Additional Deployment Options

archimate-mcp can also run as a local container (Docker / Podman / uv) or be consumed from a remote deployment. The Deployment guide has full, copy-paste mcp_config.json for all four transports — stdio, streamable-http, local container / uv, and remote URL:

• Local container / uv — launch the server from mcp_config.json via uvx, docker run, or podman run, or point at a local streamable-http container by url.
• Remote URL — connect to a server deployed behind Caddy at http://archimate-mcp.arpa/mcp using the "url" key.

Environment Variables

Variable	Description
ARCHI_MODEL_PATH	Path to the working model file (Open Exchange Format). Default ./model.archimate.
ARCHITOOL	Enable/disable the ArchiMate tool registration. Default True.

MCP Tools

Tool	Description
archi_model	Model lifecycle: new/load/save/export_exchange/import_exchange/summary
archi_element	Element CRUD: add/get/update/delete/list/find
archi_relationship	Relationship CRUD + validate: add/get/update/delete/list/validate
archi_view	Views (diagrams): create/add_element/add_connection/list/get
archi_folder	Organizations (folders): add/move/list
archi_query	Query/traversal: neighbors/relationships_of/by_type + vocabulary

Documentation

The complete documentation is published as the official documentation site and is the recommended reference for installation, deployment, and day-to-day operation.

Page	Contents
Installation	pip, source, extras, prebuilt Docker image
Deployment	run the MCP and agent servers, Compose, Caddy + Technitium, env config
Usage	the MCP tools, the ArchiApi client, the CLI
Overview	the model engine, layered façade, MCP/A2A surface
Concepts	concept registry (CONCEPT:ARCHI-*)

AGENTS.md is the canonical contributor/agent guidance.