AWS Athena MCP Server

A Model Context Protocol (MCP) server for AWS Athena that enables SQL queries and database exploration through a standardized interface.

🏗️ Project Structure

The project follows best practices for Python project organization:

aws-athena-mcp/
├── src/
│   └── athena_mcp/
│       ├── core/                 # Core system modules
│       │   ├── config.py        # Centralized configurations
│       │   ├── exceptions.py    # Custom exceptions
│       │   └── __init__.py
│       ├── services/            # Business services
│       │   ├── athena_client.py # Athena client factory and management
│       │   ├── athena_service.py # Main Athena operations
│       │   └── __init__.py
│       ├── utils/               # Utilities and helpers
│       │   ├── formatters.py    # Output formatters
│       │   ├── helpers.py       # Helper functions
│       │   ├── validators.py    # Validators
│       │   └── __init__.py
│       ├── handlers/            # MCP handlers
│       │   ├── tool_handlers.py # MCP tool handlers
│       │   └── __init__.py
│       ├── server.py            # Main MCP server
│       └── __init__.py
├── tests/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── __init__.py
├── main.py                      # Main entry point
├── setup.py                     # Installation configuration
├── pyproject.toml              # Development tools configuration
├── requirements.txt            # Dependencies
└── README.md

🚀 Features

• Modular Architecture: Code organized in well-defined modules following single responsibility principle
• Complete Type Hints: Static typing for better maintainability
• Robust Error Handling: Custom exceptions and proper error handling
• Centralized Configuration: All configurations in a single location
• Tests Included: Unit and integration test structure
• Structured Logging: Configurable logging system
• Input Validation: Validators for different data types

🔌 MCP Configuration

To use this server in MCP clients like Cursor, add the following configuration to your mcp.json file:

{
  "mcpServers": {
    "athena-connector": {
      "command": "python3",
      "args": ["/path/to/aws-athena-mcp/main.py"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key",
        "AWS_REGION": "us-east-1",
        "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/athena-results/"
      }
    }
  }
}

Configuration Options

Using Direct Credentials:

{
  "command": "python3",
  "args": ["/path/to/aws-athena-mcp/main.py"],
  "env": {
    "AWS_ACCESS_KEY_ID": "AKIA...",
    "AWS_SECRET_ACCESS_KEY": "your-secret-key",
    "AWS_REGION": "us-east-1",
    "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/results/"
  }
}

Using AWS Profile:

{
  "command": "python3",
  "args": ["/path/to/aws-athena-mcp/main.py"],