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"],
  "env": {
    "AWS_PROFILE": "your-aws-profile",
    "AWS_REGION": "us-east-1",
    "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/results/"
  }
}

Using System Default Credentials:

{
  "command": "python3",
  "args": ["/path/to/aws-athena-mcp/main.py"],
  "env": {
    "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/results/"
  }
}

Required Environment Variables

AWS_S3_OUTPUT_LOCATION: S3 location where query results will be stored

Optional Environment Variables

AWS_ACCESS_KEY_ID: AWS access key (if not using profile)
AWS_SECRET_ACCESS_KEY: AWS secret key (if not using profile)
AWS_PROFILE: Locally configured AWS profile
AWS_REGION or AWS_DEFAULT_REGION: AWS region (default: us-east-1)
LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)

⚠️ Security: For production environments, we recommend using IAM roles or AWS profiles instead of direct credentials in the configuration file.

📦 Installation

Development Installation

# Clone the repository
git clone <repository-url>
cd aws-athena-mcp

# Install in development mode
pip install -e .[dev]

Production Installation

pip install .

⚙️ Configuration

Configure the following environment variables:

# AWS credentials (optional if using profile)
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"

# AWS region
export AWS_DEFAULT_REGION="us-east-1"

# Or use an AWS profile
export AWS_PROFILE="your-profile"

# S3 output location (required)
export AWS_S3_OUTPUT_LOCATION="s3://your-bucket/athena-results/"

🎯 Usage

Run the Server

# Using the main entry point
python main.py

# Or using the installed command
athena-mcp

Available Tools

list_databases: Lists all available databases in Athena
query_athena: Executes SQL queries in Athena
describe_data_structure: Describes the structure of a database

🧪 Testing

# Run all tests
pytest

# Run only unit tests
pytest tests/unit/

# Run with coverage
pytest --cov=src/athena_mcp

# Run specific tests
pytest tests/unit/test_validators.py -v

🛠️ Development

Code Quality Tools

# Code formatting
black src/ tests/

# Import sorting
isort src/ tests/

# Type checking
mypy src/

# Linting
flake8 src/ tests/

Development Environment Setup

# Install development dependencies
pip install -e .[dev]

# Or install manually
pip install pytest pytest-asyncio black isort flake8 mypy

📋 Implemented Best Practices

Architecture

Separation of Concerns: Each module has a specific responsibility
Dependency Inversion: Use of interfaces and dependency injection
Single Responsibility Principle: Classes and functions with single purpose
Factory Pattern: For AWS client creation
Strategy Pattern: For different types of formatting and validation

Code Quality

Type Hints: Static typing in all functions and methods
Docstrings: Complete documentation in Google Style format
Error Handling: Custom exceptions and proper handling
Logging: Structured and configurable logging system
Validation: Rigorous input validation

Project Structure

src/ Layout: Clear separation between source code and other files
Namespace Packages: Hierarchical organization of modules
Test Structure: Tests organized mirroring code structure
Configuration Files: Centralized and externalized configuration

🔧 Troubleshooting

Consult the TROUBLESHOOTING.md file for common issues and solutions.

📝 Module Structure

Core (`src/athena_mcp/core/`)

config.py: Centralized system configurations
exceptions.py: Custom domain exceptions

Services (`src/athena_mcp/services/`)

athena_client.py: AWS Athena client factory and management
athena_service.py: High-level services for Athena operations

Utils (`src/athena_mcp/utils/`)

formatters.py: Formatters for different output types
helpers.py: General helper functions and utilities
validators.py: Validators for different input types

Handlers (`src/athena_mcp/handlers/`)

tool_handlers.py: Handlers for MCP tools

🤝 Contributing

Fork the project
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A Model Context Protocol server that enables SQL queries and database exploration in AWS Athena through a standardized interface.

Related MCP Servers

MSSQL MCP Server
JexinSam
-
security
A
license
-
quality
A Model Context Protocol server that enables secure and structured interaction with Microsoft SQL Server databases, allowing AI assistants to list tables, read data, and execute SQL queries with controlled access.
Last updated -
47
MIT License
MySQL-MCP
zajTools
-
security
F
license
-
quality
A Model Context Protocol server that enables SQL query execution, database management, and business intelligence capabilities through MySQL connections.
Last updated -
Microsoft SQL Server MCP Server
RichardHan
A
security
A
license
A
quality
A Model Context Protocol server that enables secure interaction with Microsoft SQL Server databases, allowing AI assistants to list tables, read data, and execute SQL queries through a controlled interface.
Last updated -
226
MIT License
MSSQL MCP Server
knight0zh
A
security
A
license
A
quality
A Model Context Protocol server that enables executing SQL queries and managing connections with Microsoft SQL Server databases.
Last updated -
1
87
6
MIT License

View all related MCP servers