Overview

This MCP (Model Context Protocol) server lets AI assistants execute SQL against AWS Athena and fetch the results programmatically. It runs as a small Node.js service that uses the Athena API to submit queries, poll for completion, and return rows (or execution identifiers) so a calling agent can continue the workflow. Use it when you want an LLM or automation agent to explore, query, and analyze datasets stored in Athena without embedding credentials or direct API calls in your assistant logic.

The server is useful for interactive exploration (previewing tables, describing schemas), scheduled or ad-hoc analytics triggered by an assistant, and for delegating long-running queries while the assistant holds onto a queryExecutionId to retrieve results later. It requires an S3 location for Athena’s query output and standard AWS credentials (CLI config, environment variables, or an IAM role).

Features

Submit SQL to Athena and return results or a queryExecutionId when timed out
Poll query status and return execution metadata (state, reason, timestamps, statistics)
Retrieve results for completed queries with configurable row limits
List and run Athena named (saved) queries in a workgroup
Configurable timeouts, retry behavior, and Athena workgroup
Runs locally or in cloud environments using existing AWS credentials

Installation / Configuration

Requirements:

Node.js >= 16
AWS credentials with Athena and S3 permissions
S3 bucket to store Athena query results

Install/run through npx as an MCP server. Example mcpServers fragment:

{
  "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": "",
        "AWS_SECRET_ACCESS_KEY": "",
        "AWS_SESSION_TOKEN": "",
        "ATHENA_WORKGROUP": "primary",
        "QUERY_TIMEOUT_MS": "300000",
        "MAX_RETRIES": "100",
        "RETRY_DELAY_MS": "500"
      }
    }
  }
}

Important environment variables:

Name	Required	Default	Description
OUTPUT_S3_PATH	Yes	—	S3 prefix for Athena query outputs, e.g. s3://bucket/path/
AWS_REGION	No	CLI default	AWS region for Athena calls
AWS_PROFILE	No	default	AWS CLI profile to use
ATHENA_WORKGROUP	No	default	Athena workgroup to run queries in
QUERY_TIMEOUT_MS	No	300000	How long to wait for a query to complete (ms)
MAX_RETRIES	No	100	Number of attempts when polling status
RETRY_DELAY_MS	No	500	Poll delay between retries (ms)

Recommended minimal IAM permissions:

athena:StartQueryExecution, GetQueryExecution, GetQueryResults, ListNamedQueries, GetNamedQuery
s3:PutObject, s3:GetObject, s3:ListBucket (for OUTPUT_S3_PATH)

Available Tools

The MCP server exposes these tools for assistants:

run_query
- Arguments: database, query, maxRows (default 1000, max 10000), timeoutMs
- Behavior: Submits SQL; returns results if it finishes within timeout, otherwise returns queryExecutionId for later retrieval.
get_status
- Arguments: queryExecutionId
- Returns: state (QUEUED | RUNNING | SUCCEEDED | FAILED | CANCELLED), stateChangeReason, submissionDateTime, completionDateTime, statistics
get_result
- Arguments: queryExecutionId, maxRows
- Returns: query rows if the execution succeeded; error if still running or failed.
list_saved_queries
- Arguments: none
- Returns: array of named queries from the configured workgroup/region (id, name, description)
run_saved_query
- Arguments: namedQueryId, databaseOverride (optional), maxRows, timeoutMs
- Behavior: Executes an existing saved query; same return semantics as run_query.

Use Cases & Examples

Show all databases:

Assistant prompt: “List all databases in Athena”
MCP payload:

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

Preview rows from a table:

Assistant prompt: “Show some rows from my_database.my_table”
MCP payload:

{
  "database": "my_database",
  "query": "SELECT * FROM my_table LIMIT 10",
  "maxRows": 10
}

Run a saved named query:

MCP payload:

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

Handle long-running queries:

Call run_query with a small timeout — if the server returns a queryExecutionId, store it.
Later call get_status(queryExecutionId) to see progress.
When SUCCEEDED, call get_result(queryExecutionId, maxRows) to fetch rows.

Checking status example:

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

Troubleshooting & Tips

Ensure OUTPUT_S3_PATH is writable by the credentials/role used.
If queries consistently time out, increase QUERY_TIMEOUT_MS or reduce query complexity.
Use workgroups to apply query limits, cost controls, and output settings centrally.
For large result sets, set maxRows appropriately; this server caps maxRows at 10,000.

Repository and source code: https://github.com/lishenxydlgzs/aws-athena-mcp

AWS Athena MCP Server for SQL Queries