AWS Athena

This MCP server lets your AI assistants run SQL queries against AWS Athena and return results, enabling dynamic data access from your Athena databases while keeping control over credentials and query configuration.

How to use

You will set up the Athena MCP server as a local, command-based MCP endpoint and then issue queries through your MCP client. Start by ensuring your AWS credentials are available to the server, then configure the Athena MCP server in your MCP configuration. You can run standard SQL commands against your Athena databases, monitor query status, fetch results, and work with saved queries for repeatable analyses.

How to install

Prerequisites you need before starting:

• Node.js v16 or later installed on the host
• NPM installed with Node.js (comes with Node)
• AWS credentials configured (via AWS CLI, environment variables, or an IAM role)

Install and run the MCP server by using the following steps. Copy the exact MCP configuration snippet into your MCP configuration file to register the Athena MCP server.

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

Ensure you provide a valid OUTPUT_S3_PATH where Athena can write query results. You can adjust optional settings like ATHENA_WORKGROUP, QUERY_TIMEOUT_MS, MAX_RETRIES, and RETRY_DELAY_MS to fit your workload and reliability needs.

Configuration overview

The server exposes the following tools to interact with Athena queries:

Tools overview

run_query — Execute a SQL query against Athena and return results or a queryExecutionId if the operation times out.

Available tools

run_query

Execute a SQL query against Athena. Returns full results if the query completes within the timeout, or returns a queryExecutionId for later retrieval when it times out.

get_status

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

get_result

Retrieve results for a completed query by its queryExecutionId. Returns full results or an error if the query failed or is still running.

list_saved_queries

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

run_saved_query

Run a previously saved query by its ID, with optional database override and row limits.