run_queryLABSCO SUMMARY
Long queries do not fail — they hand back an id you can come back to.
That is the detail that makes Athena workable from a conversation: a query that outruns the timeout returns its execution id, and the assistant polls the status and collects the rows later instead of losing the work. The response also carries data scanned in bytes, so you can see what a query cost before running a wider one.
What it is
A small Athena client over MCP: run a query, poll it, fetch its results, and browse the Glue-backed schema behind it.
What you get
- run_query — execute SQL against a named database with a max_rows cap; on timeout it returns the query execution id instead of failing
- get_status — the current state of a query: QUEUED, RUNNING, SUCCEEDED, FAILED or CANCELLED
- get_result — fetch the rows for a completed query by its execution id
- list_tables — every table in a database
- describe_table — column names, types and comments, plus index and key detail
- Results carry the execution metadata Athena charges on: data scanned in bytes, execution time, and the S3 output location
Requirements
An S3 path for query results in ATHENA_S3_OUTPUT_LOCATION — the one required setting. AWS_REGION, ATHENA_WORKGROUP and ATHENA_TIMEOUT_SECONDS are optional. AWS credentials come from the standard chain: environment variables, an AWS CLI profile, or an instance role. Install from PyPI as aws-athena-mcp and run it with uvx. The README lists the minimum Athena, S3 and Glue permissions.
Setup effort
One command plus a key — uv tool install aws-athena-mcp, then supply credentials
USE CASES
01
Getting oriented in an unfamiliar database
List the tables, then read the columns and types of the ones that look relevant.
02
Answering a question with SQL
Run the query with a row cap and read the results in the conversation.
03
Running something that takes minutes
Start the query, keep the execution id, poll the status, and fetch the rows when it succeeds.
04
Checking what a query scanned
Read the data-scanned and execution-time metadata that comes back with the result.
5 tools
Listed in project docs. Your client may show a different list.
get_statusget_resultlist_tablesdescribe_tableBEFORE YOU INSTALL
What to know first
Tools you get
5 tools named in the project's documentation.
Requires
- uvx on PATH
- AWS_ACCESS_KEY_ID in your environment
- AWS_SECRET_ACCESS_KEY in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
uv tool install aws-athena-mcpMCP Clients
Claude Desktop — uvx
CLAUDE DESKTOP — UVX · JSON
{
"mcpServers": {
"aws-athena-mcp": {
"command": "uvx",
"args": [
"aws-athena-mcp"
],
"env": {
"ATHENA_S3_OUTPUT_LOCATION": "s3://<YOUR_BUCKET>/athena-results/",
"AWS_REGION": "us-east-1",
"ATHENA_WORKGROUP": "primary",
"ATHENA_TIMEOUT_SECONDS": "60"
}
}
}
}The configuration on this page does not set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY; the project's instructions set them with an export line. An app opened from its icon or dock does not see variables exported in a terminal, so to supply them, use the block's "env" section.
Claude Desktop — installed tool
CLAUDE DESKTOP — INSTALLED TOOL · JSON
{
"mcpServers": {
"aws-athena-mcp": {
"command": "aws-athena-mcp",
"env": {
"ATHENA_S3_OUTPUT_LOCATION": "s3://<YOUR_BUCKET>/athena-results/",
"AWS_REGION": "us-east-1",
"ATHENA_WORKGROUP": "primary",
"ATHENA_TIMEOUT_SECONDS": "60"
}
}
}
}The configuration on this page does not set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY; the project's instructions set them with an export line. An app opened from its icon or dock does not see variables exported in a terminal, so to supply them, use the block's "env" section.
Claude Desktop — uv tool run
CLAUDE DESKTOP — UV TOOL RUN · JSON
{
"mcpServers": {
"aws-athena-mcp": {
"command": "uv",
"args": [
"tool",
"run",
"aws-athena-mcp"
],
"env": {
"ATHENA_S3_OUTPUT_LOCATION": "s3://<YOUR_BUCKET>/athena-results/",
"AWS_REGION": "us-east-1",
"ATHENA_WORKGROUP": "primary",
"ATHENA_TIMEOUT_SECONDS": "60"
}
}
}
}The configuration on this page does not set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY; the project's instructions set them with an export line. An app opened from its icon or dock does not see variables exported in a terminal, so to supply them, use the block's "env" section.
Claude Desktop — setup script
CLAUDE DESKTOP — SETUP SCRIPT · TERMINAL
git clone https://github.com/ColeMurray/aws-athena-mcp
cd aws-athena-mcp
python scripts/setup_claude_desktop.py
