Skip to main content
Glama
diasrafael

AWS Athena MCP Server

by diasrafael
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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

Related MCP server: MySQL-MCP

🚀 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

  1. list_databases: Lists all available databases in Athena

  2. query_athena: Executes SQL queries in Athena

  3. 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

  1. Fork the project

  2. Create a feature branch (git checkout -b feature/AmazingFeature)

  3. Commit your changes (git commit -m 'Add some AmazingFeature')

  4. Push to the branch (git push origin feature/AmazingFeature)

  5. 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
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/diasrafael/aws-athena-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server