structurizr-mcp by Cubical6 - MCP Server

Structurizr MCP Server

A Model Context Protocol (MCP) server for Structurizr, enabling AI assistants like Claude to create and manage C4 architecture diagrams as code.

✅ Production Ready - All features implemented, tested (>95% coverage), and ready for use.

What is This?

This MCP server allows Large Language Models to:

Create and manage Structurizr workspaces
Build C4 architecture models (People, Systems, Containers, Components)
Define relationships between architectural elements
Generate system context, container, and component views
Export to Structurizr DSL format

Features

✨ 23 MCP Tools - Complete workspace and model management

Workspace Management (4 tools): Create, retrieve, list, delete
C4 Model Building (5 tools): Add people, systems, containers, components, relationships
Views & Visualization (5 tools): System context, container, component, dynamic views, auto-layout
Documentation (2 tools): Add documentation sections and ADRs
Export/Import (4 tools): DSL, PlantUML, Mermaid formats
Analysis (3 tools): Dependency analysis, element search, workspace validation

🔍 7 MCP Resources - URI-based data access

Static configuration endpoint
Workspace, model, and views retrieval
Element and view-specific queries
DSL representation access

💬 7 MCP Prompts - LLM-guided assistance

Analysis: Architecture review, security analysis, improvement suggestions
Generation: System context, full C4 models, examples, C4 explanations

🏗️ Full C4 Model Support

All four C4 levels: System Context, Container, Component, Code
Dynamic views for runtime behavior
Hierarchical element organization
Complete relationship management

📝 Multiple Export Formats

Structurizr DSL (native format)
PlantUML diagrams
Mermaid diagrams
Workspace validation

🔒 Production Quality

95% test coverage (411 tests passing)
PHPStan Level 8 compliance (maximum static analysis)
PSR-12 code style compliance
Comprehensive error handling and security

🐳 Automatic CLI Detection

Automatically detects local Structurizr CLI installation
Falls back to Docker when local CLI is not available
Zero configuration needed - just works!

Installation

Prerequisites

PHP 8.1 or higher
Composer
Claude Desktop (or another MCP-compatible client)
One of the following (for DSL validation/export):
- Docker (recommended) - Automatically uses structurizr/cli image
- Structurizr CLI - Download from GitHub

Setup

Clone the repository

git clone https://github.com/Cubical6/structurizr-mcp.git
cd structurizr-mcp

Install dependencies
```
composer install
```

Configure environment (optional)

cp .env.example .env
# Edit .env if you need to customize paths or logging

Configure Claude Desktop

Add to your Claude Desktop MCP settings file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS/Linux configuration:

{
  "mcpServers": {
    "structurizr": {
      "command": "php",
      "args": ["/absolute/path/to/structurizr-mcp/server.php"]
    }
  }
}

Windows configuration:

⚠️ IMPORTANT for Windows users: You MUST escape backslashes in JSON paths by doubling them (\\) or use forward slashes (/).

Option 1: Using forward slashes (recommended)

{
  "mcpServers": {
    "structurizr": {
      "command": "php",
      "args": ["C:/Users/YourName/Projects/structurizr-mcp/server.php"]
    }
  }
}

Option 2: Using escaped backslashes

{
  "mcpServers": {
    "structurizr": {
      "command": "php",
      "args": ["C:\\Users\\YourName\\Projects\\structurizr-mcp\\server.php"]
    }
  }
}

❌ This will NOT work on Windows:

{
  "mcpServers": {
    "structurizr": {
      "command": "php",
      "args": ["C:\Users\YourName\Projects\structurizr-mcp\server.php"]
    }
  }
}

Single backslashes are invalid in JSON and will cause "Cannot read properties of undefined (reading 'cmd')" errors.

Restart Claude Desktop

Available Tools (23 Total)

Workspace Management (4 tools)

create_workspace - Create a new Structurizr workspace
get_workspace - Retrieve workspace details (JSON or DSL format)
list_workspaces - List all available workspaces
delete_workspace - Delete a workspace

Model Building (5 tools)

add_person - Add a person (user, actor) to the model
add_software_system - Add a software system
add_container - Add a container to a system
add_component - Add a component to a container
add_relationship - Create a relationship between elements

Views (5 tools)

create_system_context_view - Create a system context diagram
create_container_view - Create a container diagram
create_component_view - Create a component diagram
create_dynamic_view - Create a dynamic diagram (runtime behavior)
apply_auto_layout - Apply automatic layout to a view

Documentation (2 tools)

add_documentation_section - Add a documentation section
add_adr - Add an Architecture Decision Record

Export/Import (4 tools)

export_to_dsl - Export workspace to Structurizr DSL
export_to_plantuml - Export view to PlantUML
export_to_mermaid - Export view to Mermaid
import_from_dsl - Import workspace from DSL

Analysis (3 tools)

analyze_dependencies - Analyze element dependencies
find_element - Find elements by name
validate_workspace - Validate workspace structure

Available Resources (7 Total)

Static Resources

structurizr://config - Server configuration and status

Workspace Resources

structurizr://workspace/{workspaceId} - Full workspace data
structurizr://workspace/{workspaceId}/model - Model elements only
structurizr://workspace/{workspaceId}/views - View definitions only
structurizr://workspace/{workspaceId}/dsl - DSL representation

Element & View Resources

structurizr://workspace/{workspaceId}/element/{elementId} - Specific element data
structurizr://workspace/{workspaceId}/view/{viewKey} - Specific view data

Available Prompts (7 Total)

Analysis Prompts (3 prompts)

analyze_architecture - Comprehensive architecture analysis with 7-point framework
review_security - Security review with 6-point checklist
suggest_improvements - Improvement suggestions with customizable focus areas

Generation Prompts (4 prompts)

generate_system_context - Generate C4 system context diagram from description
create_from_description - Create complete multi-level C4 model (6-phase process)
explain_c4_model - Comprehensive C4 model explanation with examples
create_example_workspace - Generate example workspaces (e-commerce, microservices, monolith, SaaS)

Usage Examples

Example 1: Simple E-commerce System

Claude, help me create a C4 model for an e-commerce system:

1. Create a workspace called "E-commerce Platform"
2. Add a customer (person)
3. Add an e-commerce system
4. Add a payment gateway (external system)
5. Create relationships between them
6. Generate a system context view
7. Export the DSL

Claude will use the MCP tools to:

Create the workspace
Add all elements
Define relationships
Generate the view
Provide the complete DSL

Example 2: Microservices Architecture

Create a microservices architecture model:
- API Gateway system with these containers:
  - Web API (Spring Boot)
  - Redis Cache
- User Service with PostgreSQL database
- Order Service with MongoDB database
- Add relationships showing the data flow

Example 3: Inspect Existing Workspace

Show me all workspaces, then export the DSL for workspace ID ws_abc123

Architecture

structurizr-mcp/
├── server.php              # MCP server entry point
├── src/
│   ├── Configuration.php   # Environment configuration
│   ├── Tools/             # MCP tool implementations
│   │   ├── WorkspaceTools.php
│   │   └── ModelTools.php
│   ├── Structurizr/       # Core domain logic
│   │   ├── Workspace.php
│   │   ├── WorkspaceManager.php
│   │   └── DslBuilder.php
│   └── Exception/         # Custom exceptions
├── workspaces/            # Local workspace storage
├── cache/                 # Discovery cache
└── sessions/              # Session storage

Development

Run Tests

composer test

Static Analysis

composer stan

Code Style

composer cs-fix

Implementation Status

✅ Core Features - Complete

🔵 Future Enhancements (Optional)

Contributing

Contributions welcome! Please see for project documentation and for the implementation roadmap.

License

MIT License - see for details.

Resources

Support

🐛 Report Issues
📚
💬 Questions? Open a GitHub Discussion

Built with ❤️ using the PHP MCP SDK