Aws Athena MCP

What is Aws Athena MCP about?

Aws Athena MCP provides a lightweight MCP server that enables AI assistants to run SQL queries against Amazon Athena databases and retrieve the results. It abstracts credential handling, S3 result storage, and query lifecycle management so that downstream tools can focus on natural‑language interactions.

How to use Aws Athena MCP?

1. Configure AWS credentials – via the AWS CLI config, environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.), or an IAM role.
2. Add the server to your MCP configuration – use the JSON snippet below, replacing placeholders with your own values (bucket, region, workgroup, etc.).
3. Call the provided tools (run_query, get_status, get_result, list_saved_queries, run_saved_query) from your AI assistant or any MCP‑compatible client.

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

Key features of Aws Athena MCP

• run_query – Execute arbitrary SQL with optional row limit; returns full results or a queryExecutionId on timeout.
• get_status – Poll the execution state (QUEUED, RUNNING, SUCCEEDED, FAILED, CANCELLED) and view statistics.
• get_result – Fetch completed query results with a configurable row cap.
• list_saved_queries – Retrieve all named queries defined in the configured workgroup.
• run_saved_query – Execute a saved query by its ID, optionally overriding the database and timeout.
• Configurable timeouts, retries, and workgroup selection.
• Zero‑code deployment via npx.

Use cases of Aws Athena MCP

• Data exploration – Let chat‑based assistants browse databases, list tables, and preview rows without writing code.
• Reporting dashboards – Trigger Athena analyses from conversational UI and surface aggregated metrics.
• Automated monitoring – Periodically run health‑check queries and feed results into alerting pipelines.
• Ad‑hoc analytics – Business users can ask natural‑language questions that are translated into Athena SQL on‑the‑fly.

FAQ from the Aws Athena MCP

Q: Do I need to install anything locally? A: No. The server runs with npx which downloads the package at runtime.

Q: What S3 bucket is required? A: Athena writes query results to the bucket defined in OUTPUT_S3_PATH. The bucket must be in the same region and grant the executing IAM role write access.

Q: How are credentials supplied? A: Via standard AWS mechanisms – CLI config, environment variables, or the IAM role of the host instance.

Q: What is the maximum number of rows returned? A: By default 1,000 rows; the tool caps at 10,000 rows per request.

Q: Can I change the default workgroup? A: Set ATHENA_WORKGROUP in the environment to any workgroup you have permission to use.

@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:

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

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