AWS Athena MCP Server

Installation

To use the AWS Athena MCP server, you'll need to add it to your MCP configuration. The server requires AWS credentials and an S3 bucket for storing query results.

Prerequisites

1. An AWS account with access to Athena
2. An S3 bucket for storing query results
3. Appropriate IAM permissions for Athena and S3

Configuration

Add the following to your MCP configuration:

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": ["-y", "@lishenxydlgzs/aws-athena-mcp"],
      "env": {
        "OUTPUT_S3_PATH": "s3://your-bucket/athena-results/",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

AWS Authentication

The server supports multiple authentication methods:

1. AWS CLI configuration: If you have the AWS CLI installed and configured, the server will use your default credentials.
2. Environment variables: You can provide credentials via environment variables in the MCP configuration:

   "env": {
     "AWS_ACCESS_KEY_ID": "your-access-key",
     "AWS_SECRET_ACCESS_KEY": "your-secret-key",
     "AWS_SESSION_TOKEN": "your-session-token" // Optional
   }
   

3. IAM role: If running on AWS (EC2, Lambda, etc.), the server can use the instance's IAM role.

Optional Configuration

You can customize the server behavior with these additional environment variables:

• AWS_PROFILE: Specify which AWS CLI profile to use (default: "default")
• ATHENA_WORKGROUP: Specify the Athena WorkGroup (default: "primary")
• QUERY_TIMEOUT_MS: Maximum time to wait for query completion (default: 300000ms/5min)
• MAX_RETRIES: Maximum number of status check attempts (default: 100)
• RETRY_DELAY_MS: Delay between status check attempts (default: 500ms)

Usage

Once configured, you can ask your AI assistant to interact with your Athena databases. The assistant will use the appropriate tools to execute queries and retrieve results.

Example Queries

• "List all databases in my Athena account"
• "Show me the schema of the customers table in the sales database"
• "Count the number of orders by region in the last quarter"
• "Find the top 10 products by revenue"
• "Check the status of my previous query"
• "Show me all my saved queries in Athena"
• "Run my monthly sales report saved query"

Working with Large Datasets

For large datasets, consider:

1. Using the maxRows parameter to limit result size
2. Adding appropriate WHERE clauses to filter data
3. Using aggregation functions (COUNT, SUM, AVG) to summarize data

Handling Long-Running Queries

If a query takes longer than the timeout period:

1. The server will return the query execution ID
2. You can check the status using the get_status tool
3. Once complete, retrieve results with the get_result tool

Saved Queries

The MCP supports working with Athena's saved (named) queries:

1. List all saved queries with list_saved_queries
2. Execute a saved query by its ID with run_saved_query

This is useful for complex or frequently used queries that you've saved in the Athena console.