AWS Diagram MCP Server

Common errors

• ModuleNotFoundError: No module named 'mcp_server'

  cause The package `awslabs-aws-diagram-mcp-server` is installed, but you are trying to run it using an incorrect module name or path.
  fix The correct way to run the server is as a Python module: `python -m mcp_server`. Ensure `awslabs-aws-diagram-mcp-server` is installed in your active Python environment.

• requests.exceptions.ConnectionError: HTTPConnectionPool(host='127.0.0.1', port=8000): Max retries exceeded with url: /health

  cause The MCP server is not running, or it's running on a different host/port than the client is trying to connect to, or a firewall is blocking the connection.
  fix First, ensure the server is started in a separate terminal via `python -m mcp_server`. Check if another process is already using port 8000. If so, configure the server to use a different port (e.g., `MCP_SERVER_PORT=8001 python -m mcp_server`) and update your client code accordingly.

• pydantic_core._pydantic_core.ValidationError: 1 validation error for DiagramSourceCode\nbody -> diagram_source_code\n  Field required

  cause The JSON payload sent to the `/diagram` endpoint is missing the required `diagram_source_code` field or the payload is not valid JSON.
  fix Verify that your HTTP POST request's JSON payload includes a `diagram_source_code` key with a valid string containing the `diagrams` DSL, and an `output_format` key, for example: `{'diagram_source_code': '...', 'output_format': 'png'}`.

Warnings

• gotcha This package installs a server application, not a library meant for direct import of typical diagram-generating functions into your own script. You primarily run it as a module (`python -m mcp_server`) and interact with it via its HTTP API.
  Fix: Focus on interacting with the server's API (e.g., via `requests` or `curl`) after starting it, rather than trying to `import` and call functions directly within your application for diagram generation.
• gotcha The server requires Python 3.12 or higher. Attempting to install or run with earlier Python versions will result in installation failures or runtime errors.
  Fix: Ensure your development and deployment environments use Python 3.12 or a newer compatible version. Tools like `pyenv` or `conda` can help manage multiple Python versions.
• deprecated Configuration parameters, especially environment variable names for server settings like host and port, might change between major or minor versions. Always refer to the specific version's README or official documentation for accurate configuration details.
  Fix: Consult the `mcp-server` documentation on GitHub for the exact version you are using to verify configuration options, e.g., `MCP_SERVER_PORT` or `MCP_SERVER_HOST`.

Install

• pip install awslabs-aws-diagram-mcp-server Install the server application

Imports

• mcp_server

  import mcp_server

  This library is primarily a server application intended to be run via 'python -m mcp_server'. Direct programmatic import of its internal modules is generally not required for typical usage, which involves interacting with its HTTP API.

Quickstart

This quickstart demonstrates how to interact with the AWS Diagram MCP Server's API. First, ensure the server is installed (`pip install awslabs-aws-diagram-mcp-server`) and running in a separate terminal (`python -m mcp_server`). The client code then uses the `requests` library (`pip install requests`) to send a `diagrams` DSL string to the server's `/diagram` endpoint and saves the generated image locally.

import os
import requests # pip install requests

# --- Step 1: Run the MCP Server (in a separate terminal/process) ---
# The server application must be running for the client code below to work.
# In your terminal, run:
# pip install awslabs-aws-diagram-mcp-server
# python -m mcp_server
# By default, it listens on http://127.0.0.1:8000.
# You can configure host/port via environment variables (e.g., before running 'python -m mcp_server'):
# export MCP_SERVER_PORT=8001
# export MCP_SERVER_HOST=0.0.0.0

# --- Step 2: Client interaction example ---

server_host = os.environ.get('MCP_SERVER_HOST', '127.0.0.1')
server_port = os.environ.get('MCP_SERVER_PORT', '8000')
server_url = f"http://{server_host}:{server_port}"

print(f"Attempting to connect to MCP Server at {server_url}")

try:
    # Check if the server is healthy
    health_response = requests.get(f"{server_url}/health")
    health_response.raise_for_status()
    print("Server is healthy and reachable!")

    # Example of sending a diagram DSL to generate an image
    diagram_dsl = '''
from diagrams import Diagram, Cluster
from diagrams.aws.compute import EC2
from diagrams.aws.network import VPC

with Diagram("Simple Web Service", show=False, filename="simple_web_service"):
    with Cluster("Web Servers"):
        web = EC2("Web Instance")
    vpc = VPC("MyVPC")
    web >> vpc
'''

    headers = {"Content-Type": "application/json"}
    # The /diagram endpoint accepts a POST request with the DSL and desired output format.
    # The `filename` in Diagram() constructor is respected by the server.
    payload = {"diagram_source_code": diagram_dsl, "output_format": "png"}

    diagram_response = requests.post(f"{server_url}/diagram", json=payload)
    diagram_response.raise_for_status()

    # The server returns the image content directly
    output_filename = "simple_web_service.png"
    with open(output_filename, "wb") as f:
        f.write(diagram_response.content)
    print(f"Diagram '{output_filename}' generated successfully!")

except requests.exceptions.ConnectionError:
    print(f"Error: Could not connect to MCP server at {server_url}. Make sure it is running (e.g., 'python -m mcp_server') and accessible.")
except requests.exceptions.HTTPError as e:
    print(f"HTTP Error from server: {e.response.status_code} - {e.response.text}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")