Diagrams MCP

Official9 tools

by ByteOverDev · Python

Generate cloud architecture diagrams, flowcharts, and sequence diagrams.

io.github.mskry/diagrams-mcp-server — Model Context Protocol (MCP) Server

The io.github.mskry/diagrams-mcp-server is an MCP server that generates cloud architecture diagrams, flowcharts, and sequence diagrams. It provides diagram output using three rendering engines, as described in the project’s README excerpt. The repository is distributed via PyPI and includes CI and a deployed health endpoint.

🛠️ Key Features

Generates cloud architecture diagrams
Produces flowcharts
Creates sequence diagrams
Uses three rendering engines
9 tools available in the server

🚀 Use Cases

Documenting cloud architecture
Visualizing process flow with flowcharts
Describing interactions with sequence diagrams

⚡ Developer Benefits

Supports common diagram formats via multiple rendering engines
Exposes 9 MCP tools for programmatic diagram generation
Project includes CI and a health check endpoint

⚠️ Limitations

README excerpt provided is truncated and does not specify exact output types, formats, or engine details beyond “three rendering engines”

Topics

diagramsmcpmcp-servermermaid-jsmingrammerplantuml

Captured live from the server via tools/list.

render_diagram

Render a mingrammer/diagrams Python snippet to PNG and return the image. The code must be a complete Python script using `from diagrams import ...` imports and a `with Diagram(...)` context manager block. Use search_nodes to verify node names and get correct import paths before writing code. Read the diagrams://reference/diagram, diagrams://reference/edge, and diagrams://reference/cluster resources for constructor options and usage examples. Args: code: Full Python code using the diagrams library. filename: Output filename without extension. format: Output format — ``"png"`` (default), ``"svg"``, or ``"pdf"``. download_link: If True, return a temporary download URL path (/images/{token}) that expires after 15 minutes; if False, return inline image bytes. Defaults to True (URL) — set ``DIAGRAMS_INLINE_DEFAULT=true`` on the server to flip the default. SVG/PDF and PNGs larger than the inline limit always use a download link.

Parameters4

code	string	required
filename	string	optional
format	string	optional
download_link	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "filename": {
      "default": "diagram",
      "type": "string"
    },
    "format": {
      "default": "png",
      "enum": [
        "png",
        "svg",
        "pdf"
      ],
      "type": "string"
    },
    "download_link": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

list_providers

List all available diagram providers (aws, gcp, azure, k8s, onprem, etc.). Use list_providers -> list_services -> list_nodes to browse available node types for a specific provider.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_services

List service categories for a provider (e.g. 'aws' -> ['compute', 'database', ...]). Args: provider: Provider name from list_providers (e.g. 'aws', 'gcp', 'k8s').

Parameters1

provider

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string"
    }
  },
  "required": [
    "provider"
  ],
  "additionalProperties": false
}

list_nodes

List available node classes for a provider.service combo. Args: provider: Provider name (e.g. 'aws', 'gcp', 'k8s'). service: Service category (e.g. 'compute', 'database', 'network'). Returns: List of nodes with keys: name, import, alias_of (optional).

Parameters2

provider	string	required
service	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string"
    },
    "service": {
      "type": "string"
    }
  },
  "required": [
    "provider",
    "service"
  ],
  "additionalProperties": false
}

search_nodes

Search for diagram nodes by keyword across all providers and services. For targeted browsing when you know the provider, use list_providers -> list_services -> list_nodes instead. Args: query: Search term (case-insensitive substring match). Returns: List of matching nodes with keys: node, provider, service, import, alias_of (optional). Sorted by relevance: exact match first, then prefix, then substring.

Parameters1

query

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

render_mermaid

Render a Mermaid diagram definition and return the image with metadata. The definition should be valid Mermaid syntax (e.g. flowchart, sequence, class, ER, state, or Gantt diagram). Returns a list of content blocks: the rendered image plus a JSON text block with metadata including a mermaid.live edit link for opening the diagram in a browser editor. Args: definition: Mermaid diagram definition text. filename: Output filename without extension. format: Output format — ``"png"`` (default), ``"svg"``, or ``"pdf"``. download_link: If True, return a temporary download URL path (/images/{token}) that expires after 15 minutes; if False, return inline image bytes. Defaults to True (URL) — set ``DIAGRAMS_INLINE_DEFAULT=true`` on the server to flip the default. SVG/PDF and PNGs larger than the inline limit always use a download link.

Parameters4

definition	string	required
filename	string	optional
format	string	optional
download_link	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "definition": {
      "type": "string"
    },
    "filename": {
      "default": "diagram",
      "type": "string"
    },
    "format": {
      "default": "png",
      "enum": [
        "png",
        "svg",
        "pdf"
      ],
      "type": "string"
    },
    "download_link": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "definition"
  ],
  "additionalProperties": false
}

render_plantuml

Render a PlantUML diagram definition and return the image. The definition should be valid PlantUML syntax wrapped in @startuml/@enduml (sequence, class, component, activity, state, deployment, etc.). Args: definition: PlantUML diagram definition text. filename: Output filename without extension. format: Output format — ``"png"`` (default) or ``"svg"``. PDF is not supported (requires Batik/FOP). download_link: If True, return a temporary download URL path (/images/{token}) that expires after 15 minutes; if False, return inline image bytes. Defaults to True (URL) — set ``DIAGRAMS_INLINE_DEFAULT=true`` on the server to flip the default. SVG and PNGs larger than the inline limit always use a download link.

Parameters4

definition	string	required
filename	string	optional
format	string	optional
download_link	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "definition": {
      "type": "string"
    },
    "filename": {
      "default": "diagram",
      "type": "string"
    },
    "format": {
      "default": "png",
      "enum": [
        "png",
        "svg",
        "pdf"
      ],
      "type": "string"
    },
    "download_link": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "definition"
  ],
  "additionalProperties": false
}

find_equivalent

Find cross-provider equivalents for a diagram node by infrastructure role. Given a node name (e.g. 'EC2', 'Lambda', 'ComputeEngine'), returns the infrastructure role category it belongs to and the equivalent nodes from other providers. If a node name is ambiguous, use list_categories to see all mapped roles and pick a provider-specific node name. Args: node: Node class name to look up (case-insensitive, e.g. 'EC2', 'lambda'). target_provider: Optional provider to filter equivalents to (e.g. 'gcp', 'azure', 'aws'). If omitted, all equivalents across all other providers are returned. Returns: A dict with keys: category (str): Infrastructure role category name. description (str): Human-readable description of the category. source (dict): The matched node with keys node, provider, service, import. equivalents (list[dict]): Equivalent nodes, each with keys node, provider, service, import.

Parameters2

node	string	required
target_provider	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "node": {
      "type": "string"
    },
    "target_provider": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "node"
  ],
  "additionalProperties": false
}

list_categories

List all infrastructure role categories with their mapped nodes. Use this to browse all available equivalence mappings, or to disambiguate node names when find_equivalent reports ambiguity. Returns a list of category dicts, each with: category (str): Category identifier (e.g. 'virtual_machine'). description (str): Human-readable description. providers (list[str]): Providers covered by this category. nodes (dict): Mapping of provider → list of node names in that category.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

README.md9 KBView on GitHub

diagrams-mcp-server

MCP server for generating cloud architecture diagrams, flowcharts, sequence diagrams, and more — powered by three rendering engines: mingrammer/diagrams, Mermaid, and PlantUML.

Example diagram

Getting Started

Local Installation

Prerequisites

Graphviz is required for the default local/in-process rendering mode. Mermaid CLI and PlantUML are optional — install them only if you need those specific rendering engines locally.

Dependency	Required for	Install
Graphviz	`render_diagram` (cloud architecture)	`brew install graphviz`
Mermaid CLI	`render_mermaid` (flowcharts, sequence, etc.)	`npm install -g @mermaid-js/mermaid-cli`
Java + PlantUML	`render_plantuml` (UML diagrams)	`brew install openjdk` + download plantuml.jar

Install the server

Via uvx (recommended):

bash

uvx diagrams-mcp-server

Via pip:

bash

pip install diagrams-mcp-server

From source:

bash

pip install git+https://github.com/ByteOverDev/diagrams-mcp.git

Configure your MCP client

Claude Desktop

Add to your claude_desktop_config.json (Settings → Developer → Edit Config):

uvx (recommended):

json

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

pip:

json

{
  "mcpServers": {
    "diagrams-mcp": {
      "command": "diagrams-mcp-server"
    }
  }
}

Claude Code (CLI)

Run:

bash

claude mcp add diagrams-mcp -- uvx diagrams-mcp-server

Or add to your .mcp.json:

uvx (recommended):

json

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

pip:

json

{
  "mcpServers": {
    "diagrams-mcp": {
      "command": "diagrams-mcp-server"
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

uvx (recommended):

json

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

pip:

json

{
  "mcpServers": {
    "diagrams-mcp": {
      "command": "diagrams-mcp-server"
    }
  }
}

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

uvx (recommended):

json

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

pip:

json

{
  "mcpServers": {
    "diagrams-mcp": {
      "command": "diagrams-mcp-server"
    }
  }
}

VS Code

Add to your .vscode/mcp.json:

uvx (recommended):

json

{
  "servers": {
    "diagrams-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["diagrams-mcp-server"]
    }
  }
}

pip:

json

{
  "servers": {
    "diagrams-mcp": {
      "type": "stdio",
      "command": "diagrams-mcp-server"
    }
  }
}

Available Tools

Discovery

list_providers() → list[str] — List all diagram providers (aws, gcp, k8s, azure, onprem, etc.)
list_services(provider) → list[str] — List service categories within a provider (e.g. aws → compute, database, network)
list_nodes(provider, service) → list[dict] — List node classes for a provider.service pair with import paths
search_nodes(query) → list[dict] — Search for nodes by keyword across all providers (e.g. "postgres", "lambda")

Rendering

render_diagram(code) → Image (PNG) — Execute a Python script using mingrammer/diagrams in a sandboxed subprocess. Returns a rendered cloud architecture diagram.
render_mermaid(definition) → Image (PNG/SVG) — Render a Mermaid diagram definition (flowcharts, sequence, class, ER, state, Gantt, and more).
render_plantuml(definition) → Image (PNG) — Render a PlantUML diagram definition (sequence, class, component, activity, state, deployment).

Cross-Provider Equivalence

find_equivalent(node, target_provider?) → dict — Find equivalent services across cloud providers (e.g. EC2 → ComputeEngine on GCP).
list_categories() → list[dict] — List all 30 infrastructure role categories with mapped nodes across providers.

Resources

The server provides reference documentation accessible via MCP resource URIs:

URI	Description
`diagrams://reference/diagram`	Diagram constructor parameters, defaults, and usage
`diagrams://reference/edge`	Edge operators, labels, styling, and chaining
`diagrams://reference/cluster`	Cluster nesting, styling, and graph attributes
`diagrams://reference/mermaid`	Mermaid syntax examples for 6 diagram types
`diagrams://reference/plantuml`	PlantUML syntax examples for 6 diagram types

Examples

Cloud Architecture (mingrammer/diagrams)

"Draw an AWS architecture with an ALB routing to two ECS services, backed by RDS and ElastiCache"

python

from diagrams import Diagram, Cluster
from diagrams.aws.network import ALB
from diagrams.aws.compute import ECS
from diagrams.aws.database import RDS, ElastiCache

with Diagram("ECS Service", direction="LR"):
    lb = ALB("ALB")

    with Cluster("ECS Cluster"):
        services = [ECS("Web"), ECS("API")]

    lb >> services
    services[0] >> ElastiCache("Cache")
    services[1] >> RDS("Database")

Flowchart (Mermaid)

"Create a flowchart showing a CI/CD pipeline"

Mermaid flowchart

Sequence Diagram (PlantUML)

"Show the authentication flow between a client, API gateway, and auth service"

PlantUML sequence diagram

plantuml

@startuml
Client -> "API Gateway": POST /login
"API Gateway" -> "Auth Service": Validate credentials
"Auth Service" --> "API Gateway": JWT token
"API Gateway" --> Client: 200 OK + token
Client -> "API Gateway": GET /data (Bearer token)
"API Gateway" -> "Auth Service": Verify token
"Auth Service" --> "API Gateway": Valid
"API Gateway" --> Client: 200 OK + data
@enduml

Development

bash

# Clone and install
git clone https://github.com/ByteOverDev/diagrams-mcp.git
cd diagrams-mcp
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff check .
ruff format .

# Run the MCP server locally (stdio mode)
diagrams-mcp-server

Split Facade/Renderer Mode

For hosted deployments, the MCP server can run as a lightweight facade that delegates render work to a separate renderer service. This keeps the always-on MCP process small while Graphviz, Chromium, Mermaid CLI, Java, and PlantUML live only in the renderer image.

bash

# Terminal 1: renderer service
RENDERER_HOST=0.0.0.0 RENDERER_PORT=8001 diagrams-renderer-server

# Terminal 2: HTTP MCP facade delegating to the renderer
FASTMCP_TRANSPORT=http \
FASTMCP_HOST=0.0.0.0 \
FASTMCP_PORT=8000 \
DIAGRAMS_RENDERER_MODE=remote \
DIAGRAMS_RENDERER_URL=http://127.0.0.1:8001 \
diagrams-mcp-server

Docker/Railway examples are included:

File	Purpose
`Dockerfile.facade`	Slim MCP facade image without renderer-only binaries
`Dockerfile.renderer`	Renderer image with Graphviz, Chromium, Mermaid CLI, Java, and PlantUML
`railway.facade.toml`	Example Railway facade service config
`railway.renderer.toml`	Example Railway renderer service config

Key environment variables:

Variable	Purpose
`DIAGRAMS_RENDERER_MODE=remote`	Makes the facade use the HTTP renderer service
`DIAGRAMS_RENDERER_URL`	Renderer base URL, for example `http://diagrams-renderer.railway.internal:8080`
`DIAGRAMS_IMAGE_STORE_DIR`	Optional file-backed temporary image store directory
`BASE_URL`	Optional public base URL used when returning absolute download links

Supported Providers

The render_diagram tool supports all providers from the mingrammer/diagrams library, including:

AWS, GCP, Azure, Kubernetes, On-Premise, AlibabaCloud, OCI, OpenStack, DigitalOcean, Elastic, Outscale, Generic, and Custom nodes.

Use list_providers() and search_nodes(query) to discover available nodes.

License

MIT

Install

Tools (9)

render_diagramlist_providerslist_serviceslist_nodessearch_nodesrender_mermaidrender_plantumlfind_equivalent

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

io.github.mskry/diagrams-mcp-server — Model Context Protocol (MCP) Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

render_diagram

list_providers

list_services

list_nodes

search_nodes

render_mermaid

render_plantuml

find_equivalent

list_categories

diagrams-mcp-server

Getting Started

Local Installation

Prerequisites

Install the server

Configure your MCP client

Available Tools

Discovery

Rendering

Cross-Provider Equivalence

Resources

Examples

Cloud Architecture (mingrammer/diagrams)

Flowchart (Mermaid)

Sequence Diagram (PlantUML)

Development

Split Facade/Renderer Mode

Supported Providers

License

Install

Related servers