Skip to content
Back to search

diagram-mcp-server

An MCP server that seamlessly creates infrastructure diagrams for AWS, Azure, GCP, Kubernetes and more

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/andrewmoshu--diagram-mcp-server/badge.svg)](/listings/andrewmoshu--diagram-mcp-server)

HTML

<a href="/listings/andrewmoshu--diagram-mcp-server"><img src="/api/listings/andrewmoshu--diagram-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**macOS (Homebrew):**

brew install graphviz

**Ubuntu/Debian:**

sudo apt-get install graphviz graphviz-dev

**Windows (Chocolatey):**

choco install graphviz

Or download from [graphviz.org](https://graphviz.org/download/)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 604 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Infrastructure Diagram MCP Server
  2. [![PyPI version](https://badge.fury.io/py/infrastructure-diagram-mcp-server.svg)](https://pypi.org/project/infrastructure-diagram-mcp-server/)
  3. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  4. Model Context Protocol (MCP) server for Multi-Cloud Infrastructure Diagrams
  5. This MCP server seamlessly creates [diagrams](https://diagrams.mingrammer.com/) using the Python diagrams package DSL. Generate professional infrastructure diagrams for **any cloud provider** (AWS, GCP, Azure), Kubernetes, on-premises, hybrid, and multi-cloud architectures using natural language with Claude Desktop or other MCP clients.
  6. > **Note**: This is a derivative work based on [awslabs/aws-diagram-mcp-server](https://github.com/awslabs/mcp/tree/main/src/aws-diagram-mcp-server), extended with multi-cloud provider support and enhanced features.
  7. ## Prerequisites
  8. 1. Install [GraphViz](https://www.graphviz.org/) **with development headers** - Required for diagram generation and .drawio export
  9. 2. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or use `pip`
  10. 3. *(Optional)* Install [Helm](https://helm.sh/) - Required for full Helm chart parsing with `parse_helm_chart`
  11. ### Installing GraphViz
  12. **macOS (Homebrew):**
  13. ```bash
  14. brew install graphviz
  15. ```
  16. **Ubuntu/Debian:**
  17. ```bash
  18. sudo apt-get install graphviz graphviz-dev
  19. ```
  20. **Windows (Chocolatey):**
  21. ```powershell
  22. choco install graphviz
  23. ```
  24. Or download from [graphviz.org](https://graphviz.org/download/)
  25. ### Installing Helm (Optional)
  26. Helm is required for full template rendering with the `parse_helm_chart` tool. Without Helm, the parser will use a fallback mode with limited template support.
  27. **macOS (Homebrew):**
  28. ```bash
  29. brew install helm
  30. ```
  31. **Ubuntu/Debian:**
  32. ```bash
  33. curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 47 on GitHub
  34. ```
  35. **Windows (Chocolatey):**
  36. ```powershell
  37. choco install kubernetes-helm
  38. ```
  39. Or download from [helm.sh/docs/intro/install](https://helm.sh/docs/intro/install/)
  40. ## MCP Client Configuration
  41. Configure the MCP server in your MCP client. The `CFLAGS` and `LDFLAGS` (or `INCLUDE` and `LIB` on Windows) environment variables are needed for the initial build of `pygraphviz`.
  42. **Claude Desktop / Cursor on macOS** (`~/Library/Application Support/Claude/claude_desktop_config.json` or `~/.cursor/mcp.json`):
  43. ```json
  44. {
  45. "mcpServers": {
  46. "infrastructure-diagrams": {
  47. "command": "uvx",
  48. "args": ["infrastructure-diagram-mcp-server"],
  49. "env": {
  50. "FASTMCP_LOG_LEVEL": "ERROR",
  51. "CFLAGS": "-I/opt/homebrew/include",
  52. "LDFLAGS": "-L/opt/homebrew/lib"
  53. }
  54. }
  55. }
  56. }
  57. ```
  58. > **Note**: `/opt/homebrew` is the default Homebrew prefix on Apple Silicon Macs. For Intel Macs, use `/usr/local` instead.
  59. **Linux** (e.g., `~/.config/claude/claude_desktop_config.json`):
  60. ```json
  61. {
  62. "mcpServers": {
  63. "infrastructure-diagrams": {
  64. "command": "uvx",
  65. "args": ["infrastructure-diagram-mcp-server"],
  66. "env": {
  67. "FASTMCP_LOG_LEVEL": "ERROR"
  68. }
  69. }
  70. }
  71. }
  72. ```
  73. > **Note**: On Linux, install `graphviz-dev` first (`sudo apt-get install graphviz graphviz-dev`), then no extra env vars are needed.
  74. **Windows** (e.g., `%APPDATA%\Claude\claude_desktop_config.json`):
  75. ```json
  76. {
  77. "mcpServers": {
  78. "infrastructure-diagrams": {
  79. "command": "uvx",
  80. "args": ["infrastructure-diagram-mcp-server"],
  81. "env": {
  82. "FASTMCP_LOG_LEVEL": "ERROR",
  83. "INCLUDE": "C:\\Program Files\\Graphviz\\include",
  84. "LIB": "C:\\Program Files\\Graphviz\\lib"
  85. }
  86. }
  87. }
  88. }
  89. ```
  90. > **Note**: Adjust the Graphviz path if you installed it in a different location.
  91. **Other MCP Clients** (e.g., Kiro - `~/.kiro/settings/mcp.json`):
  92. ```json
  93. {
  94. "mcpServers": {
  95. "infrastructure-diagrams": {
  96. "command": "uvx",
  97. "args": ["infrastructure-diagram-mcp-server"],
  98. "env": {
  99. "FASTMCP_LOG_LEVEL": "ERROR",
  100. "CFLAGS": "-I/opt/homebrew/include",
  101. "LDFLAGS": "-L/opt/homebrew/lib"
  102. },
  103. "autoApprove": [],
  104. "disabled": false
  105. }
  106. }
  107. }
  108. ```
  109. ### Docker Installation
  110. Build and run with Docker:
  111. ```bash
  112. docker build -t infrastructure-diagram-mcp-server .
  113. ```
  114. Then configure your MCP client:
  115. ```json
  116. {
  117. "mcpServers": {
  118. "infrastructure-diagrams": {
  119. "command": "docker",
  120. "args": [
  121. "run",
  122. "--rm",
  123. "--interactive",
  124. "--env",
  125. "FASTMCP_LOG_LEVEL=ERROR",
  126. "infrastructure-diagram-mcp-server:latest"
  127. ]
  128. }
  129. }
  130. }
  131. ```
  132. ## Features
  133. The Infrastructure Diagram MCP Server provides the following capabilities:
  134. 1. **Multi-Provider Support**: Create diagrams for AWS, GCP, Azure, Kubernetes, on-premises, and hybrid/multi-cloud architectures
  135. 2. **2000+ Icons**: Access to icons across all major cloud providers and services
  136. 3. **Multiple Diagram Types**: Infrastructure architecture, sequence diagrams, flow charts, class diagrams, and more
  137. 4. **Rich Examples**: 27+ pre-built templates for AWS, GCP, Azure, K8s, hybrid, and multi-cloud patterns
  138. 5. **Customization**: Customize diagram appearance, layout, styling, colors, and connections
  139. 6. **Security**: Built-in code scanning to ensure secure diagram generation
  140. 7. **Seamless Display**: Diagrams appear inline in Claude Desktop with automatic rendering
  141. 8. **Flexible Output**: Save diagrams to PNG format in your workspace directory
  142. 9. **Editable Export**: Automatically generates .drawio files for editing in diagrams.net/draw.io
  143. 10. **IaC Parsing**: Parse Kubernetes manifests, Helm charts, and Terraform configurations to extract infrastructure information for diagram generation
  144. ## How to Use
  145. Once configured in your MCP client (e.g., Claude Desktop), you can generate diagrams using natural language:
  146. ### Example Prompts:
  147. **Discover Available Icons:**
  148. ```
  149. List all available GCP infrastructure diagram icons
  150. ```
  151. **Get Example Code:**
  152. ```
  153. Show me examples of Azure microservices diagrams
  154. ```
  155. **Generate Diagrams:**
  156. ```
  157. Create a GCP data pipeline diagram showing Pub/Sub, Dataflow, and BigQuery
  158. ```
  159. ```
  160. Generate an AWS serverless architecture with API Gateway, Lambda, and DynamoDB
  161. ```
  162. ```
  163. Design a multi-cloud architecture spanning AWS, GCP, and Azure
  164. ```
  165. **Parse Infrastructure-as-Code:**
  166. ```
  167. Parse the Kubernetes manifests in ./k8s/ and show me the resources and relationships
  168. ```
  169. ```
  170. Parse the Helm chart at ./charts/my-app/ and generate a diagram of the infrastructure
  171. ```
  172. ```
  173. Parse the Terraform configuration in ./infrastructure/ and visualize the AWS resources
  174. ```
  175. The server will automatically:
  176. 1. Find the appropriate icons from the 2000+ available
  177. 2. Generate Python code using the diagrams package
  178. 3. Create and display the PNG diagram inline
  179. 4. Save the diagram to your workspace directory
  180. 5. Generate an editable .drawio file for further customization
  181. ### Editable Diagrams with draw.io
  182. Every diagram is automatically exported in two formats:
  183. - **PNG**: For immediate viewing and sharing (displayed inline in Claude Desktop)
  184. - **.drawio**: For editing in [diagrams.net](https://app.diagrams.net) or draw.io
  185. The .drawio files allow you to:
  186. - Modify individual components, colors, and styles
  187. - Add additional notes, annotations, or documentation
  188. - Reorganize layout and positioning
  189. - Export to other formats (SVG, PDF, JPEG, etc.)
  190. - Collaborate with team members using a familiar tool
  191. Simply open the generated .drawio file in your browser at [diagrams.net](https://app.diagrams.net) - no installation required!
  192. ## What's New
  193. This fork extends the original AWS Diagram MCP Server with:
  194. - ✅ **Full Multi-Cloud Support**: GCP, Azure, Kubernetes, hybrid, and multi-cloud architectures
  195. - ✅ **27+ Comprehensive Examples**: Ready-to-use templates across all providers
  196. - ✅ **Complete Icon Coverage**: All 2000+ icons properly imported and available
  197. - ✅ **Enhanced Display**: MCP ImageContent format for seamless inline rendering
  198. - ✅ **Editable Export**: Automatic .drawio file generation for editing in diagrams.net/draw.io
  199. - ✅ **IaC Parsing**: Parse Kubernetes manifests, Helm charts, and Terraform HCL to extract infrastructure
  200. - ✅ **Bug Fixes**: Resolved double `.png` extension and read-only filesystem issues
  201. - ✅ **Icon Corrections**: Fixed 28+ incorrect class names in examples
  202. ## Code Examples
  203. Below are Python code examples showing the diagrams package syntax. When using with Claude Desktop, you can simply describe what you want in natural language!
  204. ### AWS Serverless Application
  205. ```python
  206. from diagrams import Diagram
  207. from diagrams.aws.compute import Lambda
  208. from diagrams.aws.database import Dynamodb
  209. from diagrams.aws.network import APIGateway
  210. with Diagram("Serverless Application", show=False):
  211. api = APIGateway("API Gateway")
  212. function = Lambda("Function")
  213. database = Dynamodb("DynamoDB")
  214. api >> function >> database
  215. ```
  216. ### GCP Microservices
  217. ```python
  218. from diagrams import Diagram, Cluster
  219. from diagrams.gcp.compute import CloudRun
  220. from diagrams.gcp.network import LoadBalancing
  221. from diagrams.gcp.database import SQL
  222. with Diagram("GCP Microservices", show=False):
  223. lb = LoadBalancing("load balancer")
  224. with Cluster("Services"):
  225. services = [CloudRun("api"), CloudRun("worker")]
  226. db = SQL("database")
  227. lb >> services >> db
  228. ```
  229. ### Azure Web App
  230. ```python
  231. from diagrams import Diagram
  232. from diagrams.azure.web import AppService
  233. from diagrams.azure.database import SQLServer
  234. from diagrams.azure.storage import BlobStorage
  235. with Diagram("Azure Web App", show=False):
  236. AppService("web") >> SQLServer("db") >> BlobStorage("storage")
  237. ```
  238. ### Multi-Cloud Architecture
  239. ```python
  240. from diagrams import Diagram, Cluster
  241. from diagrams.aws.compute import EC2
  242. from diagrams.gcp.compute import CloudRun
  243. from diagrams.azure.web import AppService
  244. with Diagram("Multi-Cloud Setup", show=False):
  245. with Cluster("AWS"):
  246. aws = EC2("primary")
  247. with Cluster("GCP"):
  248. gcp = CloudRun("backup")
  249. with Cluster("Azure"):
  250. azure = AppService("cdn")
  251. aws >> [gcp, azure]
  252. ```
  253. ## Example Diagrams Gallery
  254. Below are complete architecture diagram examples generated using this MCP server. These demonstrate real-world patterns across different cloud providers and deployment scenarios.
  255. ### AWS Serverless Architecture
  256. A production-ready serverless architecture using AWS services.
  257. <p align="center">
  258. <img src="examples/aws-serverless-architecture.png" alt="AWS Serverless Architecture" width="600">
  259. </p>
  260. **Architecture Components:**
  261. - Users connecting via HTTPS
  262. - API Gateway as the entry point
  263. - Multiple Lambda functions for compute
  264. - DynamoDB for NoSQL database storage
  265. ---
  266. ### GCP Serverless Architecture
  267. A serverless architecture on Google Cloud Platform with managed services.
  268. <p align="center">
  269. <img src="examples/gcp-serverless-architecture.png" alt="GCP Serverless Architecture" width="600">
  270. </p>
  271. **Architecture Components:**
  272. - Users connecting via HTTPS
  273. - Load Balancer for traffic distribution
  274. - Cloud Functions for serverless compute
  275. - Firestore for document database
  276. ---
  277. ### Azure Serverless Architecture
  278. A serverless architecture on Microsoft Azure featuring fully managed services.
  279. <p align="center">
  280. <img src="examples/azure-serverless-architecture.png" alt="Azure Serverless Architecture" width="600">
  281. </p>
  282. **Architecture Components:**
  283. - Users connecting via HTTPS
  284. - Application Gateway for routing and load balancing
  285. - Function Apps for serverless execution
  286. - Cosmos DB for globally distributed database
  287. ---
  288. ### Kubernetes Architecture
  289. A containerized application deployment on Kubernetes with full storage support.
  290. <p align="center">
  291. <img src="examples/kubernetes-architecture.png" alt="Kubernetes Architecture" width="700">
  292. </p>
  293. **Architecture Components:**
  294. - Ingress for external access and routing
  295. - Service for internal load balancing
  296. - Multiple Pods running containerized applications
  297. - Persistent Volumes and Claims for stateful storage
  298. ---
  299. ### Multi-Cloud Architecture
  300. A distributed architecture spanning AWS, GCP, and Azure with global DNS routing for high availability.
  301. <p align="center">
  302. <img src="examples/multi-cloud-architecture.png" alt="Multi-Cloud Architecture" width="500">
  303. </p>
  304. **Architecture Components:**
  305. - Global DNS (Route53) for intelligent traffic routing
  306. - **AWS Region**: ELB → Lambda → DynamoDB
  307. - **GCP Region**: Load Balancer → Cloud Functions → Firestore
  308. - **Azure Region**: Load Balancer → Function Apps → Cosmos DB
  309. ---
  310. ### Hybrid Cloud Architecture
  311. An enterprise hybrid cloud setup connecting on-premises infrastructure to AWS cloud.
  312. <p align="center">
  313. <img src="examples/hybrid-cloud-architecture.png" alt="Hybrid Cloud Architecture" width="700">
  314. </p>
  315. **Architecture Components:**
  316. - On-premises application server and PostgreSQL database
  317. - VPN Gateway for secure encrypted connectivity
  318. - AWS VPC with EC2 instances
  319. - RDS for database replication and disaster recovery
  320. - S3 for backup and archival storage
  321. ---
  322. ### GCP Foundation Organization Layer (from Terraform)
  323. A comprehensive GCP organization-level infrastructure parsed from the [terraform-example-foundation](https://github.com/terraform-google-modules/terraform-example-foundation) using the `parse_terraform` tool.
  324. <p align="center">
  325. <img src="examples/gcp_foundation_organization_layer.png" alt="GCP Foundation Organization Layer" width="800">
  326. </p>
  327. **Architecture Components:**
  328. - Organization-level resources (VPC Service Controls, Resource Tags, Org Policies)
  329. - Logging infrastructure (Cloud Logging, Pub/Sub, Storage, BigQuery sinks)
  330. - Security services (Cloud KMS, Secret Manager, Security Command Center)
  331. - CI/CD pipeline (Cloud Build, Source Repos, Artifact Registry)
  332. - Network hub (Hub VPC, Cloud NAT, Cloud Router, Interconnects)
  333. - Environment-specific shared VPCs (Dev, NonProd, Prod)
  334. ---
  335. ### Milvus Vector Database Architecture (from Helm Chart)
  336. A production-ready Milvus deployment parsed from the official [milvus-helm](https://github.com/milvus-io/milvus-helm) chart using the `parse_helm_chart` tool.
  337. <p align="center">
  338. <img src="examples/milvus-helm-architecture.png" alt="Milvus Helm Architecture" width="500">
  339. </p>
  340. **Architecture Components:**
  341. - Client access through Milvus SDK
  342. - Access Layer (Service, Deployment for milvus-proxy)
  343. - Coordinator Layer (rootcoord, querycoord, indexcoord, datacoord)
  344. - Worker Layer (querynode, indexnode, datanode)
  345. - Dependencies (etcd for metadata, MinIO for object storage, Pulsar for message queue)
  346. ---
  347. ## IaC Parsing Tools
  348. The server includes three tools for parsing Infrastructure-as-Code files:
  349. ### parse_k8s_manifest
  350. Parse Kubernetes YAML manifests to extract resources and relationships.
  351. ```
  352. Parse the K8s manifests in ./manifests/ and show me what's deployed
  353. ```
  354. **Detects:**
  355. - All K8s resource types (Deployments, Services, ConfigMaps, Secrets, PVCs, Ingress, etc.)
  356. - Relationships: Service→Deployment, Deployment→ConfigMap/Secret/PVC, Ingress→Service
  357. - Namespace grouping
  358. ### parse_helm_chart
  359. Parse Helm charts with full `helm template` rendering or fallback mode when Helm CLI is unavailable.
  360. > **Note**: For best results, [install Helm](#installing-helm-optional). Without Helm, the parser uses a fallback mode with limited Go template support.
  361. ```
  362. Parse the Helm chart at ./charts/my-app/ with values from values-prod.yaml
  363. ```
  364. **Features:**
  365. - Full Helm template rendering (requires Helm CLI)
  366. - Fallback mode for basic parsing without Helm
  367. - Custom values file and inline values support
  368. - Release name and namespace configuration
  369. ### parse_terraform
  370. Parse Terraform HCL configurations to extract resources, data sources, modules, and relationships.
  371. ```
  372. Parse the Terraform configuration in ./terraform/ and visualize the infrastructure
  373. ```
  374. **Detects:**
  375. - Resources from AWS, GCP, Azure, and Kubernetes providers
  376. - Data sources and module references
  377. - Explicit `depends_on` relationships
  378. - Implicit references between resources
  379. ---
  380. ## Development
  381. ### Testing
  382. The project includes a comprehensive test suite to ensure the functionality of the MCP server. The tests are organized by module and cover all aspects of the server's functionality.
  383. To run the tests, use the provided script:
  384. ```bash
  385. ./run_tests.sh
  386. ```
  387. This script will automatically install pytest and its dependencies if they're not already installed.
  388. Or run pytest directly (if you have pytest installed):
  389. ```bash
  390. pytest -xvs tests/
  391. ```
  392. To run with coverage:
  393. ```bash
  394. pytest --cov=infrastructure_diagram_mcp_server --cov-report=term-missing tests/
  395. ```
  396. ### Development Dependencies
  397. To set up the development environment, install the development dependencies:
  398. ```bash
  399. uv pip install -e ".[dev]"
  400. ```
  401. This will install the required dependencies for development, including pytest, pytest-asyncio, and pytest-cov.
  402. ## Troubleshooting
  403. ### `pygraphviz` build error: `graphviz/cgraph.h not found`
  404. This error occurs when the GraphViz development headers are not found during installation.
  405. **macOS:**
  406. ```bash
  407. # Make sure graphviz is installed
  408. brew install graphviz
  409. # Set compiler flags
  410. export CFLAGS="-I$(brew --prefix graphviz)/include"
  411. export LDFLAGS="-L$(brew --prefix graphviz)/lib"
  412. # Then install
  413. uvx infrastructure-diagram-mcp-server
  414. ```
  415. **Linux:**
  416. ```bash
  417. # Install development headers
  418. sudo apt-get install graphviz graphviz-dev # Ubuntu/Debian
  419. sudo dnf install graphviz-devel # Fedora/RHEL
  420. ```
  421. **Windows:**
  422. ```powershell
  423. # Install Graphviz with Chocolatey
  424. choco install graphviz
  425. # Set environment variables
  426. $env:INCLUDE = "C:\Program Files\Graphviz\include"
  427. $env:LIB = "C:\Program Files\Graphviz\lib"
  428. ```
  429. ### MCP server fails to start in Claude Desktop / Cursor
  430. 1. Make sure the `CFLAGS`/`LDFLAGS` (macOS) or `INCLUDE`/`LIB` (Windows) environment variables are set in your MCP config
  431. 2. Try clearing the uv cache: `rm -rf ~/.cache/uv`
  432. 3. Restart your MCP client
  433. ### Diagrams not displaying inline
  434. Make sure you're using a recent version of Claude Desktop or Cursor that supports MCP ImageContent.
  435. ## Contributing
  436. Contributions are welcome! Please feel free to submit a Pull Request to the [GitHub repository](https://github.com/andrewmoshu/diagram-mcp-server).
  437. ## License
  438. This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
  439. This is a derivative work based on [awslabs/aws-diagram-mcp-server](https://github.com/awslabs/mcp/tree/main/src/aws-diagram-mcp-server).
  440. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  441. See [NOTICE](NOTICE) file for additional attribution information.
  442. ## Links
  443. - **PyPI**: https://pypi.org/project/infrastructure-diagram-mcp-server/
  444. - **GitHub**: https://github.com/andrewmoshu/diagram-mcp-server
  445. - **Original Project**: https://github.com/awslabs/mcp/tree/main/src/aws-diagram-mcp-server
  446. - **Diagrams Library**: https://diagrams.mingrammer.com/

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.