AWS Athena

You can run SQL queries against your AWS Athena databases from an MCP client using this server. It executes Athena queries, supports both local stdio and remote Lambda + API Gateway deployments, offers async execution with status polling, and can work with named queries to reuse common workloads.

How to use

You connect an MCP client to the Athena MCP server either locally or remotely. In local mode, you run the server through your MCP client and provide AWS credentials and optional Athena settings. In remote mode, you deploy a serverless API that your client can call, with OAuth 2.0 authentication managed via a Cognito user pool.

Once connected, you can run SQL queries against your Athena databases, poll for their status, and retrieve results. You can also list and run previously saved (named) queries. Typical usage patterns include:

• Running ad hoc queries to explore data
• Executing longer-running queries asynchronously and polling for completion
• Managing a library of named queries for reusable data access patterns
• Retrieving partial results quickly if a query times out, then continuing later using its execution ID.

How to install

Prerequisites you need before installing:

• Node.js >= 16
• AWS credentials with permissions to use Athena and write to an S3 bucket for results
• An S3 bucket to store query results
• Optional: Cognito setup if you plan to deploy the remote, OAuth-protected API mode

Step-by-step setup for local stdio deployment (recommended for MCP clients):
1. Install Node.js from the official website (verify with `node -v` and `npm -v`).
2. Ensure AWS credentials are configured by one of the following:
   - AWS CLI configuration
   - Environment variables: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (and optionally `AWS_SESSION_TOKEN`)
   - An IAM role if running inside AWS infrastructure
3. Add the Athena MCP server to your MCP configuration using the provided stdio configuration.

Use this exact stdio configuration snippet (paste into your MCP config):

{
  "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": "default_workgroup",
        "QUERY_TIMEOUT_MS": "300000",
        "MAX_RETRIES": "100",
        "RETRY_DELAY_MS": "500"
      }
    }
  }
}

Additional deployment options

You can deploy remotely as a Lambda + API Gateway API with OAuth 2.0 authentication. The remote deployment uses interactive or quick setup scripts to build the TypeScript code, deploy with AWS SAM, create a Cognito User Pool and App Client, configure API Gateway OAuth, and generate OAuth configuration details for you to use in clients.

Configuration and security notes

Key configuration and security considerations include:

• For local deployments, ensure your AWS credentials are kept secure and not embedded in source-controlled files.
• For remote deployments, you will manage OAuth credentials (Client ID, Client Secret) and token URLs. Treat these secrets as sensitive data and do not expose them in client applications or logs.
• Use an appropriate Athena WorkGroup and region to align with your data residency and cost controls.
• Adjust timeouts and retries to balance responsiveness with reliability when large or slow-running queries are expected.

Usage examples

Show all databases in Athena
This runs a SHOW DATABASES query against your configured Athena database. Use the MCP to send:
{ "database": "default", "query": "SHOW DATABASES" }

Preview rows from a specific table
Use a SELECT with a LIMIT to fetch a small sample:
{ "database": "default", "query": "SELECT * FROM your_table LIMIT 5" }

Troubleshooting tips

If you encounter timeouts, increase QUERY_TIMEOUT_MS and MAX_RETRIES in your local config. Verify that OUTPUT_S3_PATH points to a valid S3 bucket with proper write permissions. For remote deployments, ensure your Cognito user pool and app client are correctly configured and that your client is using the generated token URL and client credentials.

Notes

Named queries can streamline repeated analyses by reusing predefined SQL statements stored in Athena. Ensure that the ATHENA_WORKGROUP and AWS_REGION align with your Athena setup to access the intended datasets.

Available tools

run_query

Execute a SQL query using AWS Athena. Returns full results if completed within timeout or the queryExecutionId for later retrieval.

get_status

Check the status of a query execution by its queryExecutionId. Returns state, timestamps, and statistics.

get_result

Retrieve results for a completed query by its queryExecutionId, up to maxRows.

list_saved_queries

List all saved (named) queries in Athena within the configured workgroup and region.

run_saved_query

Run a previously saved named query by its ID, with optional databaseOverride and maxRows.