Enables creation of AWS architecture diagrams using AWS service icons and components like Lambda, DynamoDB, API Gateway, and other AWS services through Python code generation.
Supports deployment and execution of the diagram generation server through Docker containers for creating AWS and other technical diagrams.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AWS Diagram MCP Server create a diagram for a serverless API with Lambda and DynamoDB"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) server for AWS Diagrams
This MCP server that seamlessly creates diagrams using the Python diagrams package DSL. This server allows you to generate AWS diagrams, sequence diagrams, flow diagrams, and class diagrams using Python code.
Install uv from Astral or the GitHub README
Install Python using uv python install 3.10
Install GraphViz https://www.graphviz.org/
Related MCP server: diagrams-mcp
Cursor | VS Code |
|
Configure the MCP server in your MCP client configuration.
{
"mcpServers": {
"aws-diagram-mcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/lukeburciu/aws-diagrams-mcp-server@main",
"aws-diagram-mcp-server"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
},
"autoApprove": [],
"disabled": false
}
}
}The Diagrams MCP Server provides the following capabilities:
Generate Diagrams: Create professional diagrams using Python code
Multiple Diagram Types: Support for AWS architecture, sequence diagrams, flow charts, class diagrams, and more
Customization: Customize diagram appearance, layout, and styling
Security: Code scanning to ensure secure diagram generation
from diagrams import Diagram
from diagrams.aws.compute import Lambda
from diagrams.aws.database import Dynamodb
from diagrams.aws.network import APIGateway
with Diagram("Serverless Application", show=False):
api = APIGateway("API Gateway")
function = Lambda("Function")
database = Dynamodb("DynamoDB")
api >> function >> databaseThe 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.
To run the tests, use the provided script:
./run_tests.shThis script will automatically install pytest and its dependencies if they're not already installed.
Or run pytest directly (if you have pytest installed):
pytest -xvs tests/To run with coverage:
pytest --cov=awslabs.aws_diagram_mcp_server --cov-report=term-missing tests/For more information about the tests, see the tests README.
To set up the development environment, install the development dependencies:
uv pip install -e ".[dev]"This will install the required dependencies for development, including pytest, pytest-asyncio, and pytest-cov.
Generate a diagram from Python code using the diagrams package.
This tool accepts Python code as a string that uses the diagrams package DSL and generates a PNG diagram without displaying it. The code is executed with show=False to prevent automatic display.
USAGE INSTRUCTIONS:
Never import. Start writing code immediately with with Diagram( and use the icons you found with list_icons.
First use get_diagram_examples to understand the syntax and capabilities
Then use list_icons to discover all available icons. These are the only icons you can work with.
You MUST use icon names exactly as they are in the list_icons response, case-sensitive.
Write your diagram code following python diagrams examples. Do not import any additional icons or packages, the runtime already imports everything needed.
Submit your code to this tool to generate the diagram
The tool returns the path to the generated PNG file
For complex diagrams, consider using Clusters to organize components
Diagrams should start with a user or end device on the left, with data flowing to the right.
CODE REQUIREMENTS:
Must include a Diagram() definition with appropriate parameters
Can use any of the supported diagram components (AWS, K8s, etc.)
Can include custom styling with Edge attributes (color, style)
Can use Cluster to group related components
Can use custom icons with the Custom class
COMMON PATTERNS:
Basic: provider.service("label")
Connections: service1 >> service2 >> service3
Grouping: with Cluster("name"): [components]
Styling: service1 >> Edge(color="red", style="dashed") >> service2
IMPORTANT FOR CLINE: Always send the current workspace directory when calling this tool! The workspace_dir parameter should be set to the directory where the user is currently working so that diagrams are saved to a location accessible to the user.
Supported diagram types:
AWS architecture diagrams
Sequence diagrams
Flow diagrams
Class diagrams
Kubernetes diagrams
On-premises diagrams
Custom diagrams with custom nodes
Returns: Dictionary with the path to the generated diagram and status information
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Python code using the diagrams package DSL. The runtime already imports everything needed so you can start immediately using `with Diagram(` | |
| filename | No | The filename to save the diagram to. If not provided, a random name will be generated. | |
| timeout | No | The timeout for diagram generation in seconds. Default is 90 seconds. | |
| workspace_dir | No | The user's current workspace directory. CRITICAL: Client must always send the current workspace directory when calling this tool! If provided, diagrams will be saved to a 'generated-diagrams' subdirectory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and delivers comprehensive behavioral details: it explains the tool executes code with show=False, returns a file path, has timeout control (90s default), saves to specific directories, supports various diagram types, and includes important constraints like case-sensitive icon names and no imports needed. This covers execution behavior, output format, and operational limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (USAGE INSTRUCTIONS, CODE REQUIREMENTS, etc.), but it's verbose with repetitive information (e.g., multiple mentions of workspace_dir and icon usage). Some content could be condensed without losing clarity, as not every sentence adds unique value beyond what's already stated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (code execution, file generation) and lack of annotations/output schema, the description provides complete context: it covers purpose, usage workflow, behavioral details, parameter guidance, supported diagram types, return format, and critical implementation notes. No significant gaps remain for an agent to understand and invoke the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining parameter semantics beyond the schema: it emphasizes workspace_dir as 'CRITICAL' for saving diagrams accessibly, clarifies code must start with 'with Diagram(' and use specific icons, and mentions filename generation behavior. However, it doesn't fully detail timeout implications or all parameter interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate a diagram from Python code using the diagrams package' and specifies it generates PNG output without display. It distinguishes from siblings by mentioning they should be used first for preparation (get_diagram_examples, list_icons), establishing a clear workflow hierarchy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage instructions with a numbered list (1-8), including when to use sibling tools first, specific coding requirements, and critical context like 'Always send the current workspace directory.' It clearly defines the workflow and prerequisites for successful tool invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get example code for different types of diagrams.
This tool provides ready-to-use example code for various diagram types. Use these examples to understand the syntax and capabilities of the diagrams package before creating your own custom diagrams.
USAGE INSTRUCTIONS:
Select the diagram type you're interested in (or 'all' to see all examples)
Study the returned examples to understand the structure and syntax
Use these examples as templates for your own diagrams
When ready, modify an example or write your own code and use generate_diagram
EXAMPLE CATEGORIES:
aws: AWS cloud architecture diagrams (basic services, grouped workers, clustered web services, Bedrock)
sequence: Process and interaction flow diagrams
flow: Decision trees and workflow diagrams
class: Object relationship and inheritance diagrams
k8s: Kubernetes architecture diagrams
onprem: On-premises infrastructure diagrams
custom: Custom diagrams with custom icons
all: All available examples across categories
Each example demonstrates different features of the diagrams package:
Basic connections between components
Grouping with Clusters
Advanced styling with Edge attributes
Different layout directions
Multiple component instances
Custom icons and nodes
Parameters: diagram_type (str): Type of diagram example to return. Options: aws, sequence, flow, class, k8s, onprem, custom, all
Returns: Dictionary with example code for the requested diagram type(s), organized by example name
| Name | Required | Description | Default |
|---|---|---|---|
| diagram_type | No | Type of diagram example to return. Options: aws, sequence, flow, class, k8s, onprem, custom, all | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool returns ('ready-to-use example code,' 'Dictionary with example code... organized by example name') and its educational purpose. However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions. The description adds value but lacks comprehensive behavioral context for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, usage instructions, example categories, features, parameters, returns) and front-loaded key information. However, it includes some redundancy (e.g., repeating parameter details) and could be more concise by eliminating the bulleted list of features, which adds length without critical information. Most sentences earn their place, but there's minor room for trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete. It explains the purpose, usage, parameter options, and return format. The main gap is the lack of output schema, but the description compensates by specifying the return type ('Dictionary with example code...'). It could improve by detailing error cases or example structure, but it's sufficient for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single parameter (diagram_type) with its options and default. The description repeats this information in the 'Parameters' section and adds context about what each category demonstrates (e.g., 'aws: AWS cloud architecture diagrams'), but doesn't provide significant additional semantics beyond what's in the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get example code for different types of diagrams.' It specifies the verb ('Get') and resource ('example code for different types of diagrams'), and distinguishes it from sibling tools like generate_diagram (which creates diagrams) and list_icons (which lists icons). The description explicitly mentions using these examples before creating custom diagrams with generate_diagram.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage instructions, including when to use this tool ('to understand the syntax and capabilities... before creating your own custom diagrams') and when to use an alternative ('When ready... use generate_diagram'). It also lists example categories and explains how to use the examples as templates, offering clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available icons from the diagrams package, with optional filtering.
This tool dynamically inspects the diagrams package to find available providers, services, and icons that can be used in diagrams.
USAGE INSTRUCTIONS:
Call without filters to get a list of available providers
Call with provider_filter to get all services and icons for that provider
Call with both provider_filter and service_filter to get icons for a specific service
Example workflow:
First call: list_icons() → Returns all available providers
Second call: list_icons(provider_filter="aws") → Returns all AWS services and icons
Third call: list_icons(provider_filter="aws", service_filter="compute") → Returns AWS compute icons
This approach is more efficient than loading all icons at once, especially when you only need icons from specific providers or services.
Returns: Dictionary with available providers, services, and icons organized hierarchically
| Name | Required | Description | Default |
|---|---|---|---|
| provider_filter | No | Filter icons by provider name (e.g., "aws", "gcp", "k8s") | |
| service_filter | No | Filter icons by service name (e.g., "compute", "database", "network") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool 'dynamically inspects the diagrams package,' describes the hierarchical return structure, and explains efficiency benefits. However, it doesn't mention potential limitations like rate limits, error conditions, or authentication needs, which could be relevant for a dynamic inspection tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, usage instructions, example workflow, returns) and uses bullet points effectively. It's appropriately sized for a tool with two parameters and complex usage patterns. Minor verbosity in the example workflow could be tightened, but overall it's efficient and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is largely complete. It explains the purpose, usage, parameters, and return format. The main gap is lack of output schema, but the description compensates by describing the return structure. It could benefit from more behavioral context (e.g., error handling), but covers core needs adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds value by explaining how parameters work together in a workflow (e.g., 'Call with provider_filter to get all services and icons for that provider'), but doesn't provide additional semantic details beyond what's in the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List available icons from the diagrams package, with optional filtering.' It specifies the verb ('list'), resource ('icons from the diagrams package'), and scope ('available providers, services, and icons'). It distinguishes from sibling tools like 'generate_diagram' and 'get_diagram_examples' by focusing on listing rather than generating or retrieving examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage instructions with three scenarios (no filters, provider_filter only, both filters) and an example workflow. It explains when to use this tool ('more efficient than loading all icons at once') and implies alternatives by distinguishing from sibling tools. The guidance is clear and actionable for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
generate_diagramget_diagram_exampleslist_iconsScored across 3 tools
Each tool has a clearly distinct purpose with no overlap: generate_diagram creates diagrams, get_diagram_examples provides example code, and list_icons lists available icons. The descriptions explicitly define their roles in a sequential workflow, making misselection unlikely.
All tool names follow a consistent verb_noun pattern (generate_diagram, get_diagram_examples, list_icons) with clear, descriptive verbs. There are no deviations in style or convention across the set.
With 3 tools, this is well-scoped for the server's purpose of generating AWS diagrams. Each tool earns its place by covering essential aspects: examples, icon discovery, and diagram generation, forming a complete workflow without bloat.
The tool set provides complete coverage for the diagram generation domain: get_diagram_examples for learning syntax, list_icons for resource discovery, and generate_diagram for execution. There are no obvious gaps, and the workflow guides agents from start to finish without dead ends.
Generate cloud architecture diagrams, flowcharts, and sequence diagrams.
Render, validate, encode/decode PlantUML diagram-as-code; 22 diagram types. Free, no auth.
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
