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:

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:

Configuration Options

Using Direct Credentials:

Using AWS Profile:

Using System Default Credentials:

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

Production Installation

⚙️ Configuration

Configure the following environment variables:

🎯 Usage

Run the Server

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

🛠️ Development

Code Quality Tools

Development Environment Setup

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