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.
Metadata
Release files for iflow-mcp_aws-athena-mcp 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_aws_athena_mcp-1.0.0.tar.gz | 16.6 kB | Without provenance | Details for iflow_mcp_aws_athena_mcp-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_aws_athena_mcp-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_aws_athena_mcp-1.0.0-py3-none-any.whl |
Total release size: 34.4 kB
Release files / iflow_mcp_aws_athena_mcp-1.0.0.tar.gz
| Download URL | iflow_mcp_aws_athena_mcp-1.0.0.tar.gz |
|---|---|
| Size | 16.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
82b5bfa6fb48c33c5bef93c448de6ab9581dd6ae26ffbf76894316f5f124e8e0
|
|
BLAKE2b-256 checksum How to use checksums |
b6cae06b2dc9379fbc7718193504f08cc0c191c89538b2613936108dcc6c3d04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.10 {"installer":{"name":"uv","version":"0.9.10"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_aws_athena_mcp-1.0.0-py3-none-any.whl
| Download URL | iflow_mcp_aws_athena_mcp-1.0.0-py3-none-any.whl |
|---|---|
| Size | 17.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a390145d970a515bedda96ecf4215101444c132ccd95c265a7ac8a17147e579b
|
|
BLAKE2b-256 checksum How to use checksums |
0c697ca13be71ad00a5b13b0ea303e6560ab00ce8757a0f52a055a6d3cd13c87
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.10 {"installer":{"name":"uv","version":"0.9.10"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_aws-athena-mcp 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.