https://github.com/lishenxydlgzs/aws-athena-mcp
MCP server to run AWS Athena queries
https://github.com/lishenxydlgzs/aws-athena-mcp
Last synced: 6 months ago
JSON representation
MCP server to run AWS Athena queries
- Host: GitHub
- URL: https://github.com/lishenxydlgzs/aws-athena-mcp
- Owner: lishenxydlgzs
- License: mit
- Created: 2025-02-25T17:58:25.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-04-02T09:06:56.000Z (6 months ago)
- Last Synced: 2025-04-02T10:23:49.796Z (6 months ago)
- Language: JavaScript
- Size: 43 KB
- Stars: 4
- Watchers: 1
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- Awesome-MCP-Servers-directory - AWS Athena - A MCP server for AWS Athena to run SQL queries on Glue Catalog (Databases)
- awesome-mcp-servers - AWS Athena - MCP server to run AWS Athena queries (Table of Contents / Cloud Platforms)
- awesome-mcp-servers - AWS Athena - MCP server to run AWS Athena queries (Table of Contents / Cloud Platforms)
- mcp-index - AWS Athena Query Server - Execute SQL queries against AWS Athena databases and retrieve the results for analysis and reporting. (Cloud Services)
README
# @lishenxydlgzs/aws-athena-mcp
[](https://smithery.ai/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
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:
```json
{
"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](https://github.com/lishenxydlgzs/aws-athena-mcp)