Model Context Protocol (MCP) server for executing AWS Athena queries, enabling AI assistants to run SQL queries against AWS Athena databases and retrieve results.

Installation

NPX

npx -y @lishenxydlgzs/aws-athena-mcp

Configuration

MCP Configuration

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": ["-y", "@lishenxydlgzs/aws-athena-mcp"],
      "env": {
        // Required
        "OUTPUT_S3_PATH": "s3://your-bucket/athena-results/",
        
        // Optional AWS configuration
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default",
        "AWS_ACCESS_KEY_ID": "",
        "AWS_SECRET_ACCESS_KEY": "",
        "AWS_SESSION_TOKEN": "",
        
        // Optional server configuration
        "ATHENA_WORKGROUP": "default_workgroup",
        "QUERY_TIMEOUT_MS": "300000",
        "MAX_RETRIES": "100",
        "RETRY_DELAY_MS": "500"
      }
    }
  }
}

Available Tools

Tool	Description
run_query	Execute a SQL query using AWS Athena with parameters for database, query, and maximum number of rows
get_status	Check the execution status of a query by queryExecutionId
get_result	Retrieve results from a completed query by queryExecutionId
list_saved_queries	List all saved (named) queries in Athena
run_saved_query	Execute a previously saved query by its ID with optional database override

Features

• Execute SQL queries against AWS Athena databases
• Retrieve query results with configurable row limits (up to 10,000)
• Check query execution status and statistics
• Handle long-running queries with timeout and retry mechanisms
• Manage saved queries in Athena workgroups
• Support for multiple AWS authentication methods

Environment Variables

Required

• OUTPUT_S3_PATH - S3 bucket path for storing Athena query results

Optional

• AWS_REGION - AWS region for Athena operations
• AWS_PROFILE - AWS CLI profile to use
• AWS_ACCESS_KEY_ID - AWS access key ID for authentication
• AWS_SECRET_ACCESS_KEY - AWS secret access key for authentication
• AWS_SESSION_TOKEN - AWS session token for temporary credentials
• ATHENA_WORKGROUP - Athena workgroup for query execution
• QUERY_TIMEOUT_MS - Query timeout in milliseconds (default: 300000ms)
• MAX_RETRIES - Maximum number of retry attempts (default: 100)

Usage Examples

List all databases in Athena

Show me all tables in the default database

What's the schema of the asin_sitebestimg table?

Show some rows from my_database.mytable

Find the average price by category for in-stock products

Notes

Requires Node.js >= 16, AWS credentials with appropriate permissions for Athena and S3, and an S3 bucket for query results. Supports AWS CLI configuration, environment variables, and IAM roles for authentication.