The @lishenxydlgzs/aws-athena-mcp server enables AI assistants to interact with AWS Athena databases by executing and managing SQL queries.
Capabilities include:
Run SQL queries: Execute custom SQL queries against specified Athena databases
Get query results: Retrieve results for completed queries, limited by a maximum number of rows
Check query status: Monitor the status of query executions, including state, timestamps, and statistics
List saved queries: Fetch all named (saved) queries in Athena
Run saved queries: Execute previously saved queries by their ID, with optional configuration overrides
Configure AWS credentials: Supports multiple credential configurations including CLI, environment variables, and IAM roles
Customize query execution: Set parameters like timeout, maximum retries, and Athena workgroup
Requires Node.js >= 16 to run the MCP server
@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
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)
Add the server to your MCP configuration:
The server provides the following tools:
run_query
: Execute a SQL query using AWS AthenaParameters:
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 executionParameters:
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 queryParameters:
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 optionaldescription
Queries are returned from the configured
ATHENA_WORKGROUP
andAWS_REGION
run_saved_query: Run a previously saved query by its ID.
Parameters:
namedQueryId
: ID of the saved querydatabaseOverride
: Optional override of the saved query's default databasemaxRows
: 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:
List Tables in a Database
Message to AI Assistant:
Show me all tables in the default database
MCP parameter:
Get Table Schema
Message to AI Assistant:
What's the schema of the asin_sitebestimg table?
MCP parameter:
Table Rows Preview
Message to AI Assistant:
Show some rows from my_database.mytable
MCP parameter:
Advanced Query with Filtering and Aggregation
Message to AI Assistant:
Find the average price by category for in-stock products
MCP parameter:
Checking Query Status
Getting Results for a Completed Query
Listing Saved Queries
Running a Saved Query
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
andAWS_REGION
License
MIT
Repository
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Run SQL queries with AWS Athena to access data available from AWS Glue catalog.
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityA server that enables LLMs like Claude to query AWS DynamoDB databases through natural language requests, supporting table management, data querying, and schema analysis.Last updated -76MIT License
- -securityFlicense-qualityA Model Context Protocol server that enables SQL queries and database exploration in AWS Athena through a standardized interface.Last updated -4
- -securityFlicense-qualityRun queries and pull information about your TigerData Cloud's PostgreSQL databasesLast updated -
- AsecurityAlicenseAqualityProvides flexible access to Oracle databases for AI assistants like Claude, supporting SQL queries across multiple schemas with comprehensive database introspection capabilities.Last updated -65MIT License