archon-mcp

MCP server for generating C4 architecture diagrams via AI agents. Works with Cursor AI, Claude Desktop, Windsurf, and any MCP-compatible client.

Generates JSON files loadable in the Archon visual architecture tool.

Features

• 15 tools — create projects, add systems, containers, users, relationships, groups, integration layers, business scenarios, ports, and auto-install Cursor rules
• Stateful — project accumulates across tool calls within a session
• Smart Visibility — parent systems are automatically included in integration layers if their containers are visible
• Custom Anchor Points (Ports) — add specific connection points to elements for cleaner diagrams with many relationships
• Name-based references — all element references use names (auto-resolved to UUIDs)
• Full C4 model — systems, containers (App/DB/Bus), users, relationships with technologies and endpoints
• Integration layers — multiple diagram views showing different subsets of the architecture
• Business scenarios — step-by-step data flow narratives with annotations
• Visual groups — infrastructure boundaries (Kubernetes, VPC, DMZ)
• Built-in quality rules — tool descriptions guide AI agents to produce comprehensive architectures
• One-command Cursor Rule setup — setup_cursor_rule installs quality requirements into any project

Quick Start

Cursor AI

Add to your Cursor MCP settings (Cursor Settings → MCP → Add New MCP Server):

• Name: archon-mcp
• Type: command
• Command: npx -y archon-mcp

Or add a .cursor/mcp.json file to your project root:

{
  "mcpServers": {
    "archon-mcp": {
      "command": "npx",
      "args": ["-y", "archon-mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "archon-mcp": {
      "command": "npx",
      "args": ["-y", "archon-mcp"]
    }
  }
}

Windsurf / Other MCP Clients

Same pattern — configure the MCP server with command npx and args ["-y", "archon-mcp"].

Setting Up Quality Rules (Recommended)

After configuring the MCP server, ask your AI agent:

"Run setup_cursor_rule to install the Archon quality rules"

This creates .cursor/rules/archon.mdc in your project with:

• Minimum element counts (6-12 systems, 40+ relationships, 3-5 business scenarios)
• Thinking checklist (databases, messaging, security, observability, edge)
• Tool workflow order
• Color scheme and detail requirements

Without this rule, agents may produce minimal architectures. With it, they generate production-grade diagrams.

Usage

Once configured, just ask your AI agent:

"Create an architecture diagram for an e-commerce platform"

"Design a banking infrastructure with microservices"

"Draw a C4 diagram for a real-time messaging system"

The agent will call the tools in sequence and produce a JSON file you can load in Archon.

Tools

| Tool | Description | |------|-------------| | setup_cursor_rule | Install Archon quality rules into .cursor/rules/ | | create_project | Initialize a new architecture project | | add_systems | Add systems (bounded contexts) | | add_containers | Add containers: App, DB, or Bus | | add_users | Add actors/personas | | add_relationships | Add connections between elements | | add_groups | Add visual boundaries (K8s, VPC, DMZ) | | add_layer_groups | Add folders for organizing layers | | add_integration_layers | Add diagram views with element visibility | | add_scenario_groups | Add folders for organizing scenarios | | add_business_scenarios | Add step-by-step data flow narratives | | add_ports | Add custom anchor points (ports) to elements | | get_project_info | Get project summary and element counts | | save_project | Save project to JSON file |

Workflow

1. create_project("My Architecture")
2. add_systems([...])             — 6-12 systems
3. add_containers([...])          — 3-6 per system (App/DB/Bus)
4. add_users([...])               — 3-5 actors
5. add_relationships([...])       — 40+ connections
6. add_groups([...])              — infrastructure boundaries
7. add_layer_groups([...])        — layer folders
8. add_integration_layers([...])  — 3-5 views (one isDefault:true)
9. add_scenario_groups([...])     — scenario folders
10. add_business_scenarios([...]) — 3-5 step-by-step flows
11. add_ports([...])              — add anchor points (optional)
12. save_project("architecture.json")

Anchor Points (Ports)

Use add_ports when an element has many connections to avoid overlapping lines.

• left / right ports: work from TOP to BOTTOM (y-axis)
• top / bottom ports: work from LEFT to RIGHT (x-axis)
• In add_relationships, use fromSide, toSide, fromPortId, toPortId to connect to specific ports.

Container Types

| Type | Description | Default Color | |------|-------------|---------------| | App | Application, microservice, API, worker | #6366f1 | | DB | Database (PostgreSQL, Redis, MongoDB...) | #10b981 | | Bus | Event bus / Message queue (Kafka, RabbitMQ...) | #a855f7 |

Example

User: "Create a simple web app architecture"

Agent calls:
  create_project({ name: "Web App" })
  add_systems({ items: [
    { name: "Frontend", description: "React SPA" },
    { name: "Backend", description: "API services" },
    { name: "Data", description: "Storage layer" }
  ]})
  add_containers({ items: [
    { name: "React App", systemName: "Frontend", type: "App", technologies: ["React", "TypeScript"] },
    { name: "API Server", systemName: "Backend", type: "App", technologies: ["Node.js", "Express"] },
    { name: "PostgreSQL", systemName: "Data", type: "DB", schemas: ["users", "posts"] },
    { name: "Redis Cache", systemName: "Data", type: "DB", technologies: ["Redis"] }
  ]})
  add_users({ items: [{ name: "User", description: "End user" }] })
  add_relationships({ items: [
    { from: "User", to: "React App", description: "Uses", technology: "HTTPS" },
    { from: "React App", to: "API Server", description: "API calls", technology: "REST" },
    { from: "API Server", to: "PostgreSQL", description: "Queries", technology: "SQL" },
    { from: "API Server", to: "Redis Cache", description: "Caching", technology: "Redis Protocol" }
  ]})
  add_integration_layers({ items: [{ name: "Full View", isDefault: true }] })
  save_project({ fileName: "web-app.json" })

Loading in Archon

1. Run the Archon app
2. Click Load Project in the toolbar
3. Select the generated .json file
4. Explore the architecture with layers, scenarios, and element details

Manual Cursor Rule Setup

If you prefer to set up the rule manually instead of using setup_cursor_rule, create .cursor/rules/archon.mdc:

---
description: Archon C4 architecture generation via MCP tools
alwaysApply: true
---

# Archon MCP — Architecture Generation Rules

When asked to create architecture diagrams, use archon-mcp tools.

## Requirements
- 6-12 systems, 3-6 containers per system, 3-5 users, 40+ relationships
- 3-5 integration layers (one isDefault:true), 3-5 business scenarios
- Container types: ONLY "App", "DB", "Bus"
- Every relationship: fill description AND technology
- Every DB: fill schemas. Every Bus: fill topics
- Think about: security, observability, messaging, edge, data storage

## Ports (Anchor Points)
Use `add_ports` when an element has many connections.
- `left` / `right` ports: TOP to BOTTOM
- `top` / `bottom` ports: LEFT to RIGHT
- Use `fromSide`, `toSide`, `fromPortId`, `toPortId` in `add_relationships`.

Development

git clone https://github.com/alexfromgithub/archon-mcp.git
cd archon-mcp
npm install
npm run build # Includes obfuscation and minification
npm start

License

MIT