AWS Athena MCP Server

A Model Context Protocol (MCP) server for AWS Athena, designed to integrate with n8n AI agents.

Overview

This MCP server provides a standardized way for n8n AI agents to query AWS Athena and retrieve data. It implements the Model Context Protocol, allowing n8n agents to:

1. List available databases and tables
2. Get table schemas and metadata
3. Execute SQL queries and retrieve results

Features

- Simple API for interacting with Athena from n8n AI agents
- Built-in health checks and monitoring
- Configurable through environment variables
- Containerized for easy deployment
- Kubernetes-ready with sample EKS manifests

Prerequisites

- AWS account with Athena access
- AWS credentials with appropriate permissions
- Docker for local development/testing
- Kubernetes/EKS for production deployment

Environment Variables

The server is configured using the following environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| AWS_REGION | AWS region for Athena | us-east-1 |
| ATHENA_CATALOG | Athena catalog name | AwsDataCatalog |
| ATHENA_DATABASE | Default database to use | None |
| ATHENA_WORKGROUP | Athena workgroup to use | primary |
| ATHENA_OUTPUT_LOCATION | S3 location for query results | None (required) |
| HOST | Host to bind the server | 0.0.0.0 |
| PORT | Port to listen on | 8050 |

Available Tools

The MCP server provides the following tools to n8n AI agents:

execute_query

Execute SQL queries against Athena and retrieve results.

Parameters:
- query (string, required): SQL query to execute
- database (string, optional): Database name
- catalog (string, optional): Catalog name
- output_location (string, optional): S3 location for results
- workgroup (string, optional): Workgroup name
- max_results (integer, optional): Maximum number of results to return
- max_wait_seconds (integer, optional): Maximum time to wait for query completion

list_databases

List available databases in a catalog.

Parameters:
- catalog (string, optional): Catalog name

list_tables

List tables in a specific database.

Parameters:
- database (string, required): Database name
- catalog (string, optional): Catalog name

get_table_metadata

Get metadata for a specific table, including column definitions.

Parameters:
- table (string, required): Table name
- database (string, required): Database name
- catalog (string, optional): Catalog name

Local Development

Installation

1. Clone the repository:

git clone https://github.com/yourusername/aws-athena-mcp-server.git

cd aws-athena-mcp-server

2. Install dependencies:

pip install -r requirements.txt

3. Configure AWS credentials:

export AWS_ACCESS_KEY_ID=your_access_key

export AWS_SECRET_ACCESS_KEY=your_secret_key

export AWS_REGION=your_region

export ATHENA_OUTPUT_LOCATION=s3://your-bucket/folder/

4. Run the server:

python main.py

The server will be available at http://localhost:8050.

Docker Setup

Building the Docker Image

docker build -t athena-mcp-server:latest .

Running the Docker Container

docker run -p 8050:8050 \
  -e AWS_REGION=us-east-1 \
  -e ATHENA_OUTPUT_LOCATION=s3://your-bucket/folder/ \
  -e AWS_ACCESS_KEY_ID=your_access_key \
  -e AWS_SECRET_ACCESS_KEY=your_secret_key \
  athena-mcp-server:latest

Deploying to AWS EKS

Prerequisites

- AWS CLI configured with appropriate permissions
- kubectl installed and configured to connect to your EKS cluster
- Docker installed for building images

Deployment Steps

1. Build and push the Docker image to ECR:

```bash