AWS Athena MCP Server

How to use

You connect to the MCP server from an MCP client and issue tools to run queries, fetch results, and inspect schemas. The server exposes tools for executing SQL, checking status, retrieving results, listing tables in a database, and describing table schemas. Start the server using one of the supported runtime commands, then point your MCP client at the running process. Typical usage patterns include launching a long-running query, polling for status, and streaming results as they become available.

How to install

Prerequisites: you need Python installed and, optionally, the uv, uvx, or npx tool ecosystems available depending on how you want to run the server.

# From PyPI with uv (recommended for Claude Desktop)
uv tool install aws-athena-mcp

# From PyPI with pip
pip install aws-athena-mcp

# Or from source
git clone https://github.com/ColeMurray/aws-athena-mcp
cd aws-athena-mcp
pip install -e .

Additional setup steps

Configure environment variables to enable Athena access and set basic behavior. The required setting is the location for Athena query results, with optional defaults for region, workgroup, and timeout.

export ATHENA_S3_OUTPUT_LOCATION=s3://your-bucket/athena-results/
export AWS_REGION=us-east-1
export ATHENA_WORKGROUP=primary
export ATHENA_TIMEOUT_SECONDS=60

Starting the MCP server

Choose one of the following runtime methods to start the MCP server after you’ve installed and configured it.

# Start the MCP server (if installed with uv tool install)
aws-athena-mcp

# Or run directly with uv (without installing)
uv tool run aws-athena-mcp

# Or run directly with uvx (without installing)
uvx aws-athena-mcp

# Or run directly with Python
python -m athena_mcp.server

Claude Desktop integration (optional)

If you use Claude Desktop, configure an MCP server entry so Claude can talk to the AWS Athena MCP server.

{
  "mcpServers": {
    "aws-athena-mcp": {
      "command": "uvx",
      "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"
      }
    }
  }
}

AWS credentials and permissions

Configure AWS credentials so the MCP server can access Athena and S3. Use environment variables, AWS CLI configuration, or an AWS profile.

# Option 1: Environment variables
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key

# Option 2: AWS CLI
aws configure

# Option 3: AWS Profile
export AWS_PROFILE=your-profile

Security and best practices

Protect the MCP server from unauthorized access, use TLS for communications, and consider VPC endpoints for AWS services in production. Apply least-privilege IAM policies to ensure only needed actions are allowed.

Troubleshooting

If you encounter configuration or credentials issues, verify the required environment variable is set and that your AWS credentials have the needed permissions for Athena and S3.

# Common checks
echo $ATHENA_S3_OUTPUT_LOCATION
aws sts get-caller-identity

Tools exposed by the server

The server provides tools to execute queries and discover schemas.

run_query

Execute SQL queries against Athena and return results.

get_status

Check the status of an in-flight or completed query.

get_result

Retrieve results for a finished query execution.

list_tables

List all tables in a given database.

describe_table

Describe the schema of a specific table.