What is AWS Athena

The @lishenxydlgzs/aws-athena-mcp is a Model Context Protocol (MCP) server designed to facilitate the execution of SQL queries against AWS Athena databases by AI assistants. It enables users to seamlessly retrieve query results from Athena, streamlining data access and manipulation tasks within AWS environments.

Use cases

This MCP server can be used in various scenarios, such as querying databases to fetch data for reporting, performing data analysis through advanced SQL queries, retrieving table schemas, listing available databases and tables, and managing saved queries in Athena. It’s particularly useful for tasks in data-driven applications and analytics workflows.

How to use

To use the server, configure AWS credentials via the AWS CLI, environment variables, or IAM roles, and then add the server to your MCP configuration. You can execute queries using the run_query function, check query statuses with get_status, retrieve query results with get_result, and manage saved queries through dedicated functionalities. Each function requires specified parameters for operation.

Key features

Key features of the aws-athena-mcp include executing SQL queries against Athena, fetching query execution status, retrieving results, listing saved queries, and running saved queries. It also supports customizing settings such as output locations, workgroups, and query timeouts, enhancing its usability across different user needs and AWS accounts.

Where to use

This MCP server is ideal for environments that utilize AWS Athena for data queries, such as business intelligence tools, data analysis applications, and AI-powered assistance systems. It is well-suited for developers and data scientists looking to integrate SQL query capabilities into their applications or enhance automated data retrieval processes.

@lishenxydlgzs/aws-athena-mcp

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.

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:

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:

{
  "database": "default",
  "query": "SHOW DATABASES"
}

List Tables in a Database

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

MCP parameter:

{
  "database": "default",
  "query": "SHOW TABLES"
}

Get Table Schema

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

MCP parameter:

{
  "database": "default",
  "query": "DESCRIBE default.asin_sitebestimg"
}

Table Rows Preview

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

MCP parameter:

{
  "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:

{
  "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

{
  "queryExecutionId": "12345-67890-abcdef"
}

Getting Results for a Completed Query

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

Listing Saved Queries

{
  "name": "list_saved_queries",
  "arguments": {}
}

Running a Saved Query

{
  "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