{"id":7960,"library":"awslabs-aws-diagram-mcp-server","title":"AWS Diagram MCP Server","description":"The AWS Diagram MCP Server is a Python application that hosts an API for generating architectural diagrams. It leverages the popular `diagrams` Python package, allowing users to submit Diagram as Code (DaC) definitions (using the `diagrams` DSL) via HTTP endpoints and receive image outputs. It is currently at version 1.0.23 and follows an active, irregular release cadence driven by feature development and bug fixes.","status":"active","version":"1.0.23","language":"en","source_language":"en","source_url":"https://github.com/awslabs/mcp.git","tags":["aws","diagrams","mcp","architecture","server","fastapi","iac"],"install":[{"cmd":"pip install awslabs-aws-diagram-mcp-server","lang":"bash","label":"Install the server application"}],"dependencies":[],"imports":[{"note":"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.","symbol":"mcp_server","correct":"import mcp_server"}],"quickstart":{"code":"import os\nimport requests # pip install requests\n\n# --- Step 1: Run the MCP Server (in a separate terminal/process) ---\n# The server application must be running for the client code below to work.\n# In your terminal, run:\n# pip install awslabs-aws-diagram-mcp-server\n# python -m mcp_server\n# By default, it listens on http://127.0.0.1:8000.\n# You can configure host/port via environment variables (e.g., before running 'python -m mcp_server'):\n# export MCP_SERVER_PORT=8001\n# export MCP_SERVER_HOST=0.0.0.0\n\n# --- Step 2: Client interaction example ---\n\nserver_host = os.environ.get('MCP_SERVER_HOST', '127.0.0.1')\nserver_port = os.environ.get('MCP_SERVER_PORT', '8000')\nserver_url = f\"http://{server_host}:{server_port}\"\n\nprint(f\"Attempting to connect to MCP Server at {server_url}\")\n\ntry:\n    # Check if the server is healthy\n    health_response = requests.get(f\"{server_url}/health\")\n    health_response.raise_for_status()\n    print(\"Server is healthy and reachable!\")\n\n    # Example of sending a diagram DSL to generate an image\n    diagram_dsl = '''\nfrom diagrams import Diagram, Cluster\nfrom diagrams.aws.compute import EC2\nfrom diagrams.aws.network import VPC\n\nwith Diagram(\"Simple Web Service\", show=False, filename=\"simple_web_service\"):\n    with Cluster(\"Web Servers\"):\n        web = EC2(\"Web Instance\")\n    vpc = VPC(\"MyVPC\")\n    web >> vpc\n'''\n\n    headers = {\"Content-Type\": \"application/json\"}\n    # The /diagram endpoint accepts a POST request with the DSL and desired output format.\n    # The `filename` in Diagram() constructor is respected by the server.\n    payload = {\"diagram_source_code\": diagram_dsl, \"output_format\": \"png\"}\n\n    diagram_response = requests.post(f\"{server_url}/diagram\", json=payload)\n    diagram_response.raise_for_status()\n\n    # The server returns the image content directly\n    output_filename = \"simple_web_service.png\"\n    with open(output_filename, \"wb\") as f:\n        f.write(diagram_response.content)\n    print(f\"Diagram '{output_filename}' generated successfully!\")\n\nexcept requests.exceptions.ConnectionError:\n    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.\")\nexcept requests.exceptions.HTTPError as e:\n    print(f\"HTTP Error from server: {e.response.status_code} - {e.response.text}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0 (and potentially early 1.x before 3.12 was enforced)"},{"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`.","message":"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.","severity":"deprecated","affected_versions":"Potentially between 0.x and 1.x or future major versions."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The package `awslabs-aws-diagram-mcp-server` is installed, but you are trying to run it using an incorrect module name or path.","error":"ModuleNotFoundError: No module named 'mcp_server'"},{"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.","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.","error":"requests.exceptions.ConnectionError: HTTPConnectionPool(host='127.0.0.1', port=8000): Max retries exceeded with url: /health"},{"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'}`.","cause":"The JSON payload sent to the `/diagram` endpoint is missing the required `diagram_source_code` field or the payload is not valid JSON.","error":"pydantic_core._pydantic_core.ValidationError: 1 validation error for DiagramSourceCode\\nbody -> diagram_source_code\\n  Field required"}]}