AWS Athena

by lishenxydlgzs

9 stars
623 downloads
Not rated
GitHub

About

Integrates with AWS SDK to execute SQL queries against Athena databases, enabling large-scale data analysis and business intelligence for AWS data lakes.

Details

Author
lishenxydlgzs
Repository
lishenxydlgzs/aws-athena-mcp
GitHub stars
9
Downloads
623
License
MIT License
Categories
Database, Other, File Management, Design, Developer Tools, AI, Cloud Service, Infrastructure
Tags
#integration

Jump to

- Execute SQL queries on AWS Athena
- Retrieve results synchronously or asynchronously with query execution IDs
- Check query status and statistics using execution IDs
- List and run saved (named) queries from Athena
- Configurable query timeout, retry behavior, and workgroup
- Supports AWS credentials via CLI, environment variables, or IAM roles

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name AWS Athena
    Command (node, npx, python, etc.) npx
    Arguments
    • Argument 1 -y
    • Argument 2 @lishenxydlgzs/aws-athena-mcp
    Environment
    • AWS_REGION us-east-1
    • AWS_PROFILE default
    • MAX_RETRIES 100
    • OUTPUT_S3_PATH s3://your-bucket/athena-results/
    • RETRY_DELAY_MS 500
    • ATHENA_WORKGROUP default_workgroup
    • QUERY_TIMEOUT_MS 300000
    • AWS_ACCESS_KEY_ID
    • AWS_SESSION_TOKEN
    • AWS_SECRET_ACCESS_KEY

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

1. Configure AWS credentials using one of the following methods:
- AWS CLI configuration
- Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
- IAM role (if running on AWS)

2. Add the server to your 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",                    // Default: AWS CLI default region
        "AWS_PROFILE": "default",                     // Default: 'default' profile
        "AWS_ACCESS_KEY_ID": "",                      // Optional: AWS access key
        "AWS_SECRET_ACCESS_KEY": "",                  // Optional: AWS secret key
        "AWS_SESSION_TOKEN": "",                      // Optional: AWS session token
        
        // Optional server configuration
        "ATHENA_WORKGROUP": "default_workgroup",      // Optional: specify the Athena WorkGroup
        "QUERY_TIMEOUT_MS": "300000",                 // Default: 5 minutes (300000ms)
        "MAX_RETRIES": "100",                         // Default: 100 attempts
        "RETRY_DELAY_MS": "500"                       // Default: 500ms between retries
      }
    }
  }
}

3. The server provides the following tools:

- run_query: Execute a SQL query using AWS Athena
- Parameters:
- database: The Athena database to query
- query: SQL query to execute
- maxRows: Maximum number of rows to return (default: 1000, max: 10000)
- Returns:
- If query completes within timeout: Full query results
- If timeout reached: Only the queryExecutionId for later retrieval

- get_status: Check the status of a query execution
- Parameters:
- queryExecutionId: The ID returned from run_query
- Returns:
- state: Query state (QUEUED, RUNNING, SUCCEEDED, FAILED, or CANCELLED)
- stateChangeReason: Reason for state change (if any)
- submissionDateTime: When the query was submitted
- completionDateTime: When the query completed (if finished)
- statistics: Query execution statistics (if available)

- get_result: Retrieve results for a completed query
- Parameters:
- queryExecutionId: The ID returned from run_query
- maxRows: Maximum number of rows to return (default: 1000, max: 10000)
- Returns:
- Full query results if the query has completed successfully
- Error if query failed or is still running

- list_saved_queries: List all saved (named) queries in Athena.

- Returns:
- An array of saved queries with id, name, and optional description
- Queries are returned from the configured ATHENA_WORKGROUP and AWS_REGION

- run_saved_query: Run a previously saved query by its ID.
- Parameters:
- namedQueryId: ID of the saved query
- databaseOverride: Optional override of the saved query's default database
- maxRows: Maximum number of rows to return (default: 1000)
- timeoutMs: Timeout in milliseconds (default: 60000)
- Returns:
- Same behavior as run_query: full results or execution ID

---

{
  "queryExecutionId": "12345-67890-abcdef",
  "maxRows": 10
}

{
  "name": "run_saved_query",
  "arguments": {
    "namedQueryId": "abcd-1234-efgh-5678",
    "maxRows": 100
  }
}

---

run_query

Execute a SQL query using AWS Athena. Parameters: database (string), query (string), maxRows (optional integer, default: 1000, max: 10000). Returns full query results if completed within timeout, otherwise returns queryExecutionId.

get_status

Check the status of a query execution. Parameters: queryExecutionId (string). Returns state, stateChangeReason, submissionDateTime, completionDateTime, and statistics.

get_result

Retrieve results for a completed query. Parameters: queryExecutionId (string), maxRows (optional integer, default: 1000, max: 10000). Returns full query results if completed successfully, or an error if failed or still running.

list_saved_queries

List all saved (named) queries in Athena. Returns an array of saved queries with id, name, and optional description.

run_saved_query

Run a previously saved query by its ID. Parameters: namedQueryId (string), databaseOverride (optional string), maxRows (optional integer, default: 1000), timeoutMs (optional integer, default: 60000). Returns similar behavior as run_query.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

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

@lishenxydlgzs/aws-athena-mcp

smithery badge

A Model Context Protocol (MCP) server for running AWS Athena queries. This server enables AI assistants to execute SQL queries against your AWS Athena databases and retrieve results.

<a href="https://glama.ai/mcp/servers/0i7dhkex6t">
aws-athena-mcp MCP server
</a>

Usage

1. Configure AWS credentials using one of the following methods:
- AWS CLI configuration
- Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
- IAM role (if running on AWS)

2. Add the server to your 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",                    // Default: AWS CLI default region
        "AWS_PROFILE": "default",                     // Default: 'default' profile
        "AWS_ACCESS_KEY_ID": "",                      // Optional: AWS access key
        "AWS_SECRET_ACCESS_KEY": "",                  // Optional: AWS secret key
        "AWS_SESSION_TOKEN": "",                      // Optional: AWS session token
        
        // Optional server configuration
        "ATHENA_WORKGROUP": "default_workgroup",      // Optional: specify the Athena WorkGroup
        "QUERY_TIMEOUT_MS": "300000",                 // Default: 5 minutes (300000ms)
        "MAX_RETRIES": "100",                         // Default: 100 attempts
        "RETRY_DELAY_MS": "500"                       // Default: 500ms between retries
      }
    }
  }
}

3. The server provides the following tools:

- run_query: Execute a SQL query using AWS Athena
- Parameters:
- database: The Athena database to query
- query: SQL query to execute
- maxRows: Maximum number of rows to return (default: 1000, max: 10000)
- Returns:
- If query completes within timeout: Full query results
- If timeout reached: Only the queryExecutionId for later retrieval

- get_status: Check the status of a query execution
- Parameters:
- queryExecutionId: The ID returned from run_query
- Returns:
- state: Query state (QUEUED, RUNNING, SUCCEEDED, FAILED, or CANCELLED)
- stateChangeReason: Reason for state change (if any)
- submissionDateTime: When the query was submitted
- completionDateTime: When the query completed (if finished)
- statistics: Query execution statistics (if available)

- get_result: Retrieve results for a completed query
- Parameters:
- queryExecutionId: The ID returned from run_query
- maxRows: Maximum number of rows to return (default: 1000, max: 10000)
- Returns:
- Full query results if the query has completed successfully
- Error if query failed or is still running

- list_saved_queries: List all saved (named) queries in Athena.

- Returns:
- An array of saved queries with id, name, and optional description
- Queries are returned from the configured ATHENA_WORKGROUP and AWS_REGION

- run_saved_query: Run a previously saved query by its ID.
- Parameters:
- namedQueryId: ID of the saved query
- databaseOverride: Optional override of the saved query's default database
- maxRows: Maximum number of rows to return (default: 1000)
- timeoutMs: Timeout in milliseconds (default: 60000)
- Returns:
- Same behavior as run_query: full results or execution ID

---

Usage Examples

Show All Databases

Message to AI Assistant: ``List all databases in Athena

MCP parameter:
json { "database": "default", "query": "SHOW DATABASES" } 


List Tables in a Database

Message to AI Assistant:
Show me all tables in the default database

MCP parameter:
json { "database": "default", "query": "SHOW TABLES" } 


Get Table Schema

Message to AI Assistant:
What's the schema of the asin_sitebestimg table?

MCP parameter:
json { "database": "default", "query": "DESCRIBE default.asin_sitebestimg" } 


Table Rows Preview

Message to AI Assistant:
Show some rows from my_database.mytable

MCP parameter:
json { "database": "my_database", "query": "SELECT FROM my_table LIMIT 10", "maxRows": 10 } 


Advanced Query with Filtering and Aggregation

Message to AI Assistant:
Find the average price by category for in-stock products

MCP parameter:
json { "database": "my_database", "query": "SELECT category, COUNT() as count, AVG(price) as avg_price FROM products WHERE in_stock = true GROUP BY category ORDER BY count DESC", "maxRows": 100 } 


Checking Query Status
json { "queryExecutionId": "12345-67890-abcdef" } 


Getting Results for a Completed Query
json { "queryExecutionId": "12345-67890-abcdef", "maxRows": 10 } 


Listing Saved Queries
json { "name": "list_saved_queries", "arguments": {} } 


Running a Saved Query
json { "name": "run_saved_query", "arguments": { "namedQueryId": "abcd-1234-efgh-5678", "maxRows": 100 } } `

---

Requirements

- Node.js >= 16
- AWS credentials with appropriate Athena and S3 permissions
- S3 bucket for query results
- Named queries (optional) must exist in the specified ATHENA_WORKGROUP and AWS_REGION`

---

License

MIT

Repository

GitHub Repository

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

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

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other