# alexei-led/aws-mcp-server architecture

> Architecture diagram of the GitHub repository alexei-led/aws-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexei-led/aws-mcp-server
- Repository: https://github.com/alexei-led/aws-mcp-server

## Overview

##### Main Components
- AI Assistant(s): These are external clients such as Claude Desktop, Cursor, or Windsurf that interact with the service using the MCP protocol.
- AWS MCP Server: The core service, implemented in Python (under src/aws_mcp_server), which parses the commands and acts as a gateway.
- AWS CLI: The subprocess component inside the server that executes the actual AWS commands.
- AWS Cloud: External AWS services that the executed CLI commands communicate with.
- Docker Container: Since the recommended deployment uses Docker, include a container component that encapsulates the server environment.
- Configuration & Infrastructure Components: Environment variables (like AWS_MCP_TIMEOUT, AWS_MCP_MAX_OUTPUT, AWS_PROFILE, etc.) and volumes (for mounting AWS credentials into the container) that configure and secure the system.

##### Relationships and Data Flow
- The AI Assistant sends a request via the MCP protocol to the AWS MCP Server.
- The server receives the command, validates it, and then uses a subprocess call to execute the corresponding AWS CLI command.
- The AWS CLI executes the command and the results are returned to the server.
- Finally, the server processes the command output and sends a formatted response back to the AI Assistant.
- How Docker volumes mount the AWS credentials read-only into the container, ensuring secure command execution.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The system clearly isolates the role of the AI assistant, the AWS MCP Server, and the AWS CLI execution.
- Containerization: Docker isolates the server process from the host system and provides consistent environments.
- Extensibility: Predefined prompt templates and command validation help extend functionality and maintain security.
- Test & Integration: Presence of both unit and integration tests demonstrates the importance of verification across components.

##### Relevant Technologies and Frameworks
- Python 3.13+ as the programming language.
- Docker for containerization and multi-architecture support.
- AWS CLI (as a subprocess within the server) for interacting with AWS Services.
- CI/CD tools (GitHub Actions workflows and Codecov) for continuous testing and coverage.
- Configuration management through environment variables, emphasizing security by mounting AWS credentials as read-only.

## Diagram (Mermaid)

```mermaid
flowchart TD
    AIA["AI Assistant (Claude Desktop, Cursor, Windsurf)"]:::external

    subgraph "Docker Container"
        S["AWS MCP Server"]:::server
        CL["AWS CLI"]:::cli
        DNote["Mounted AWS Credentials (Read-only)"]:::note
        SConfig["Configuration Management"]:::config
        SPrompts["Command Prompt Templates"]:::prompts
    end

    AC["AWS Cloud"]:::cloud

    DCK["Docker Deployment"]:::container

    CI["CI/CD Pipelines"]:::cicd
    TEST["Integration & Unit Testing"]:::tests

    %% Data Flow
    AIA -->|"MCPProtocol"| S
    S -->|"SubprocessCall"| CL
    CL -->|"APIRequests/Responses"| AC
    AC -->|"Response"| CL
    CL -->|"ProcessResult"| S
    S -->|"FormattedResponse"| AIA

    %% Internal AWS MCP Server Dependencies
    S -->|"uses"| SConfig
    S -->|"uses"| SPrompts

    %% Additional relationships
    S --- CI
    S --- TEST

    %% Indicate Docker Deployment relation
    DCK -.-> S

    %% Click Events
    click S "https://github.com/alexei-led/aws-mcp-server/tree/main/src/aws_mcp_server"
    click CL "https://github.com/alexei-led/aws-mcp-server/blob/main/src/aws_mcp_server/cli_executor.py"
    click SConfig "https://github.com/alexei-led/aws-mcp-server/blob/main/src/aws_mcp_server/config.py"
    click SPrompts "https://github.com/alexei-led/aws-mcp-server/blob/main/src/aws_mcp_server/prompts.py"
    click DCK "https://github.com/alexei-led/aws-mcp-server/tree/main/deploy/docker"
    click TEST "https://github.com/alexei-led/aws-mcp-server/tree/main/tests"
    click CI "https://github.com/alexei-led/aws-mcp-server/tree/main/.github/workflows"

    %% Styles
    classDef external fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef server fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
    classDef cli fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef cloud fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef container fill:#d1c4e9,stroke:#512da8,stroke-width:2px;
    classDef note fill:#f8bbd0,stroke:#c2185b,stroke-width:2px,stroke-dasharray:5,5;
    classDef config fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef prompts fill:#dcedc8,stroke:#558b2f,stroke-width:2px;
    classDef cicd fill:#ffcdd2,stroke:#c62828,stroke-width:2px;
    classDef tests fill:#d7ccc8,stroke:#5d4037,stroke-width:2px;
```
