Diagrams

A local/remote MCP server for generating infrastructure and architecture diagrams as code using the Python [diagrams](https://diagrams.mingrammer.com/) library

## Features

**5 Diagram Tools** for infrastructure, architecture, and flowcharts:

- **Infrastructure Diagrams** - 15+ providers (AWS, Azure, GCP, K8s, On-Prem, SaaS)
- **500+ Node Types** - Compute, database, network, storage, security
- **Custom Icons** - Web URLs (HTTPS) and local files
- **Flowcharts** - 24 shapes for process diagrams
- **Validation** - Dry-run before generation

**Advanced Capabilities:**

- Multiple output formats (PNG, PDF, JPG, DOT)
- Cluster grouping with unlimited nesting
- Edge styling (colours, labels, line styles)
- Graphviz attribute customisation

## Installation

**System Requirements:**

- Graphviz must be installed:
- macOS: `brew install graphviz`
- Ubuntu/Debian: `sudo apt-get install graphviz`
- Windows: Download from https://graphviz.org/download/

### IDEs

[](vscode:mcp/install?%7B%22name%22%3A%22diagrams%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22diagrams-mcp%22%5D%7D)

[](https://cursor.com/en-US/install-mcp?name=diagrams&config=eyJjb21tYW5kIjoidXZ4IGRpYWdyYW1zLW1jcCJ9)

### Claude Desktop

Add to your `claude_desktop_config.json`:

**For published package:**

```json
{
"mcpServers": {
"diagrams": {
"command": "uvx",
"args": ["diagrams-mcp"]
}
}
}
```

**For local development:**

```json
{
"mcpServers": {
"diagrams:local": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/diagrams-mcp",
"run",
"diagrams-mcp"
]
}
}
}
```

### Claude Code

**Quick setup (CLI):**

Published package:

```bash
claude mcp add --transport stdio math -- uvx diagrams-mcp
```

**Team setup (project-level):**

Add `.mcp.json` to your project root:

```json
{
"mcpServers": {
"diagrams": {
"command": "uvx",
"args": ["diagrams-mcp"]
}
}
}
```

**Verify installation:**

```bash
claude mcp list
```

Or check in IDE: View → MCP Servers, or use `/mcp` command.

## Try It

Once installed, try these prompts:

- "Create an AWS 3-tier web application diagram with Route53, ELB, EC2 instances, and RDS"
- "Generate a Kubernetes microservices architecture with ingress, services, and pods"
- "Build a flowchart for a CI/CD pipeline with decision points"
- "Create a diagram using a custom icon from my company logo URL"
- "Show me all available AWS compute nodes"

Map to tools: `create_diagram`, `create_diagram_with_custom_icons`, `create_flowchart`, `list_available_nodes`, `validate_diagram_spec`

## Tool Reference

All tool parameters and descriptions are available in your IDE's autocomplete.

### Diagram Generation (3 tools)

| Tool | Description |
| ---------------------------------- | ------------------------------------------------------------ |
| `create_diagram` | Full infrastructure/architecture diagrams with all providers |
| `create_diagram_with_custom_icons` | Diagrams with custom node icons from URLs or local files |
| `create_flowchart` | Simplified flowchart creation with 24 process shapes |

### Discovery & Validation (2 tools)

| Tool | Description |
| ----------------------- | ------------------------------------------------------------- |
| `list_available_nodes` | Search 500+ available nodes by provider, category, or keyword |
| `validate_diagram_spec` | Dry-run validation before generation |

## Custom Icons

### Web URL Icons

- HTTPS-only (HTTP rejected)
- 5MB file size limit
- 5-second download timeout
- Image format validation (PNG, JPG)
- Automatic caching (~/.diagrams_mcp/icon_cache)

### Local File Icons

- Path validation (file must exist)
- Format validation
- Sandboxed execution