Skip to main content
Glama
Azure Diagram MCP Server

Azure Diagram MCP Server

by Jah-yee

Azure Diagram MCP Server

Tests PyPI License: MIT Python 3.12+ MCP Copilot SDK

An MCP server for generating professional infrastructure diagrams using the Python diagrams DSL — with first-class Azure support and GitHub Copilot SDK integration for natural language diagram generation.

graph LR
    A[AI Assistant] -->|Natural Language| B[MCP Server]
    B -->|Python DSL| C[Diagrams + Graphviz]
    C -->|PNG| D[MCP Apps Viewer]
    B -->|Security Scan| E[AST + Bandit]
    E -->|Pass| C

Getting Started

Step 1 — Install Prerequisites

Dependency

Install

Verify

uv

astral.sh/uv

uv --version

Python 3.12+

uv python install 3.12

python3 --version

Graphviz

brew install graphviz / apt install graphviz / graphviz.org

dot -V

⚠️ Graphviz is required. Without it the MCP server will fail to start. Verify with dot -V before proceeding.

Step 2 — Verify the Server Starts

Run the server directly to confirm everything works:

uvx microsoft.azure-diagram-mcp-server

You should see a message confirming the server is installed and ready. The server is an MCP stdio server — it's designed to be launched by an MCP client, not run directly. If it fails to install, check that Graphviz is installed (dot -V).

Step 3 — Connect to Your AI Host

Pick one of the methods below to register the server with your AI host.

Copilot CLI

  1. Start a Copilot CLI session:

    copilot
  2. Inside the session, run the slash command:

    /mcp add
  3. Fill in the form (use Tab to move between fields):

    Field

    Value

    Name

    azure-diagram

    Type

    Local

    Command

    uvx microsoft.azure-diagram-mcp-server

  4. Press Ctrl+S to save.

  5. Verify with /mcp show azure-diagram — status should show ✓ Connected.

The config is saved to ~/.copilot/mcp-config.json. You can also edit that file directly:

{
  "servers": {
    "azure-diagram": {
      "type": "local",
      "command": "uvx microsoft.azure-diagram-mcp-server",
      "tools": ["*"]
    }
  }
}

VS Code (one-click)

Install on VS Code

Or add manually to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "azure-diagram": {
        "command": "uvx",
        "args": ["microsoft.azure-diagram-mcp-server"],
        "env": {
          "FASTMCP_LOG_LEVEL": "ERROR"
        }
      }
    }
  }
}

Docker

docker build -t microsoft/azure-diagram-mcp-server .
{
  "mcp": {
    "servers": {
      "azure-diagram": {
        "command": "docker",
        "args": ["run", "--rm", "-i", "--env", "FASTMCP_LOG_LEVEL=ERROR",
                 "microsoft/azure-diagram-mcp-server:latest"]
      }
    }
  }
}

Related MCP server: fcp-drawio

Features

Feature

Description

☁️ Azure-First

100+ Azure service icons — App Service, Functions, Cosmos DB, AKS, and more

🌐 Multi-Cloud

AWS, GCP, Kubernetes, on-premises, and custom icon support

📊 Multiple Types

Architecture, sequence, flow, class, K8s, and custom diagrams

🔒 Security Scanning

AST + Bandit code analysis before every execution

🖼️ MCP Apps Viewer

Interactive diagram viewer with pan, zoom, download, and dark/light theme

🤖 Copilot SDK

Natural language diagram generation via GitHub Copilot SDK

Architecture

graph TB
    subgraph "GitHub Copilot"
        CLI[Copilot CLI]
        VS[VS Code Copilot]
    end

    subgraph "MCP Server"
        S[server.py<br/>FastMCP]
        DT[diagram_tools.py<br/>Generation + Examples]
        SC[scanner.py<br/>AST + Bandit]
        V[viewer/app.html<br/>MCP Apps Viewer]
    end

    subgraph "Copilot SDK Layer"
        CC[copilot_client.py<br/>DiagramCopilotClient]
        AG[Custom Agent<br/>azure-diagram-architect]
    end

    CLI & VS -->|MCP stdio| S
    CC -->|MCP local| S
    AG --> CC
    S --> DT
    S --> V
    DT --> SC
    SC -->|Pass| DT
    DT -->|Python DSL| GV[Graphviz → PNG]

MCP Tools

Tool

Description

generate_diagram

Execute Python diagram code with security scanning and timeout. Pre-imports all providers — just start with with Diagram(...).

refresh_diagram

Regenerate a diagram from updated code (app-only, used by the MCP Apps viewer).

get_diagram_examples

Get example code by type: azure, sequence, flow, class, k8s, onprem, custom, or all.

list_icons

Discover available icons by provider and service. Filter with provider_filter and service_filter.

sequenceDiagram
    participant User
    participant Copilot as GitHub Copilot
    participant MCP as MCP Server
    participant App as MCP Apps Viewer

    User->>Copilot: "Create an Azure web app diagram"
    Copilot->>MCP: list_icons(provider_filter="azure")
    MCP-->>Copilot: Available icons
    Copilot->>MCP: get_diagram_examples(diagram_type="azure")
    MCP-->>Copilot: Example code
    Copilot->>MCP: generate_diagram(code="...")
    MCP-->>Copilot: PNG + structuredContent
    Copilot->>App: Render diagram in viewer
    App-->>User: Interactive diagram with pan/zoom

MCP Apps Viewer

The server includes an interactive MCP Apps viewer that renders diagrams inline in VS Code and the Copilot CLI. When generate_diagram returns a result, the viewer is automatically displayed.

graph LR
    subgraph "MCP Server"
        GD[generate_diagram] -->|CallToolResult| SC[structuredContent<br/>status + imageData]
        SC --> META["_meta.ui.resourceUri<br/>ui://diagram-viewer/app.html"]
    end

    subgraph "MCP Apps Viewer"
        META --> V[Interactive Viewer]
        V --> PAN[Pan & Drag]
        V --> ZOOM[Zoom In/Out]
        V --> DL[Download PNG]
        V --> THEME[Dark/Light Theme]
        V --> FIT[Fit to View]
    end

Feature

Control

Pan

Click and drag

Zoom

Mouse wheel, + / - keys

Fit to view

0 key or toolbar button

Download

Toolbar download button

Theme

Toggle dark/light in toolbar

The viewer is served as an MCP resource at ui://diagram-viewer/app.html and receives the diagram as base64-encoded PNG via structuredContent.imageData.

Quick Example

from diagrams import Diagram
from diagrams.azure.compute import AppServices, FunctionApps
from diagrams.azure.database import CosmosDb
from diagrams.azure.network import ApplicationGateway

with Diagram("Azure Web Architecture", show=False):
    gateway = ApplicationGateway("Gateway")
    app = AppServices("App Service")
    functions = FunctionApps("Functions")
    db = CosmosDb("Cosmos DB")

    gateway >> app >> db
    gateway >> functions >> db

Copilot SDK Integration

The server includes a GitHub Copilot SDK client that provides a natural language interface to diagram generation — describe what you want and the Copilot-powered architect generates it.

graph LR
    U[User Prompt] --> CC[DiagramCopilotClient]
    CC -->|Creates Session| CS[CopilotClient]
    CS -->|Connects| MCP[Diagram MCP Server]
    CS -->|Uses| AG[azure-diagram-architect<br/>Custom Agent]
    MCP -->|Returns| IMG[PNG Diagram]

Interactive CLI

uv run microsoft.azure-diagram-copilot

Programmatic Usage

import asyncio
from microsoft.azure_diagram_mcp_server.copilot_client import DiagramCopilotClient

async def main():
    async with DiagramCopilotClient(model="gpt-4.1") as client:
        client.on_delta(lambda delta: print(delta, end="", flush=True))
        client.on_idle(lambda: print())

        await client.generate(
            "Create a 3-tier Azure architecture with App Gateway, "
            "App Service, and Cosmos DB"
        )

asyncio.run(main())

BYOK (Bring Your Own Key)

Use your own LLM provider — no Copilot subscription required:

Variable

Description

DIAGRAM_COPILOT_PROVIDER_TYPE

openai, azure, or anthropic

DIAGRAM_COPILOT_BASE_URL

API endpoint URL

DIAGRAM_COPILOT_API_KEY

API key

DIAGRAM_COPILOT_WIRE_API

completions or responses

DIAGRAM_COPILOT_MODEL

Model override (default: gpt-4.1)

DIAGRAM_COPILOT_AZURE_API_VERSION

Azure API version (default: 2024-10-21)

export DIAGRAM_COPILOT_PROVIDER_TYPE=azure
export DIAGRAM_COPILOT_BASE_URL=https://your-resource.openai.azure.com
export DIAGRAM_COPILOT_API_KEY=your-api-key
uv run microsoft.azure-diagram-copilot

Resumable Sessions

client = DiagramCopilotClient(session_id="my-project-diagrams")
await client.start()
await client.generate("Create an Azure web app diagram")

# Resume later
await client.resume("my-project-diagrams")
await client.generate("Add a Redis cache to the previous diagram")
await client.stop()

Development

# Setup
uv sync --group dev

# Test (140 tests, 9 skip without Graphviz)
uv run pytest tests/ -v

# Lint + format
uv run ruff check microsoft/ tests/
uv run ruff format --check microsoft/ tests/

# Type check
uv run pyright

# Coverage
uv run pytest --cov=microsoft --cov-report=term-missing tests/

See AGENTS.md for comprehensive contributor documentation covering architecture, conventions, testing patterns, CI/CD, and the GitHub Pages docs site.

Documentation

📖 microsoft.github.io/diagrams-mcp-server — Full documentation built with VitePress, deployed via GitHub Pages.

cd docs-site && npm install && npm run docs:dev  # Local dev server

License

This project is licensed under the MIT License — see the LICENSE file for details.

Contributing

This project welcomes contributions and suggestions. See AGENTS.md for the full development guide.

Available Tools

4 tools
generate_diagramB

Generate a diagram from Python code using the diagrams package DSL.

Inputs: code (required), filename, timeout, workspace_dir.

get_diagram_examplesC

Get example diagram code for the specified diagram type.

Inputs: diagram_type.

list_iconsB

List available diagram icons organized by provider and service.

Inputs: provider_filter, service_filter.

refresh_diagramC

Regenerate a diagram from updated code (app-only tool).

Inputs: code (required), filename, timeout, workspace_dir.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: generating diagrams, fetching examples, listing icons, and refreshing. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, making the set predictable and easy to navigate.

    Tool Count4/5

    With 4 tools, the set is well-scoped for generating and managing diagrams, though slightly thin for a full lifecycle.

    Completeness3/5

    Core operations are covered, but missing features like editing, exporting, or deleting diagrams create gaps that agents may need to work around.

    Related MCP Connectors

    Related MCP Servers