home / mcp / athena analytics mcp server

Athena Analytics MCP Server

Provides read-only access to Athena data in S3 with query validation, templates, and redaction for safe NLP-based analytics.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "elena-kuznetsova-wh-warehouse-athena-mcp": {
      "url": "http://mcp-athena-server:8000/sse",
      "headers": {
        "MCP_AUTH_TOKEN": "YOUR_TOKEN_HERE",
        "ATHENA_ANALYTICS_INTERNAL": "ATHENA_ANALYTICS_INTERNAL"
      }
    }
  }
}

You can securely query analytics data stored in S3 using AWS Athena through an MCP server. It provides controlled access for Claude and other LLMs, with strong security bounds, query validation, and data redaction to keep your analytics safe while enabling natural language exploration and reporting.

How to use

Connect your MCP-enabled client to the Athena Analytics MCP server to run read-only queries, explore table schemas, and render template-based reports. Use the available tools to execute validated ad-hoc queries, run parameterized templates, list tables, or fetch table schemas. The server enforces strict query validation, redacts sensitive data, and applies resource limits to protect your data and infrastructure.

How to install

Prerequisites you need before installation are Docker and Docker Compose, plus AWS credentials that allow access to Athena data in S3. You also need an Athena setup prepared for use by the MCP server.

# 1. Create environment file with credentials (example shown; adapt paths as needed)
cp mcp_athena_analytics/.env.example ~/.mcp_athena_analytics.env

# 2. Start Claude Code sandbox environment (Docker network is created automatically)
docker-compose up -d

# 3. Start MCP Athena Analytics server container (joins the Claude network)
docker-compose up -d --build

# 4. Verify the MCP server is running
docker ps | grep mcp-athena-server
curl http://localhost:8000/health

Once the server reports a healthy status, configure your MCP client with the server endpoint and the authentication token you generate and store securely.

Configuration and security notes

Key security and configuration details you should know include: the MCP server isolates credentials inside its container, there is a Bearer token authentication boundary between components, and all results are sanitized before returning to the client. AWS credentials are refreshed automatically using IRSA in Kubernetes deployments, with a read-only default profile for sandbox or replica buckets.

Important security layers also include query validation (only read-only SELECT/WITH allowed, with a blacklist for potentially destructive templates), data sanitization that redacts sensitive fields, and strict resource limits (maximum rows and timeout) to prevent abuse.

Tool usage and examples

The server provides four MCP tools you can invoke from your MCP client to interact with Athena data without writing SQL manually. Use them to run templates with validated parameters, execute ad-hoc queries, and discover tables and schemas.

{
  "tool": "execute_query",
  "arguments": {
    "sql_query": "SELECT COUNT(*) FROM provider__actions_alpha WHERE year = 2024"
  }
}
```
```json
{
  "tool": "execute_template",
  "arguments": {
    "template_name": "AGG_RTP",
    "params": {"year": 2024, "month": 1, "brand": "alpha"}
  }
}

Troubleshooting

If you encounter startup or credential issues, ensure Docker services are running, AWS credentials are available to the MCP server, and that the MCP_AUTH_TOKEN you use in your client matches what you generated during setup. For authentication, verify the token and ensure the server health endpoint responds as healthy.

Common problems and fixes include checking for missing Python modules, ensuring PYTHONPATH includes the analytics code, and confirming that AWS credentials are configured for the ATHENA_ANALYTICS_INTERNAL profile. If queries time out, consider narrowing date ranges or using partition filters and aggregated tables.

Additional notes

The MCP server architecture emphasizes security boundaries: HTTP API as the main boundary, containerized credentials isolation, and network isolation through a Docker bridge. It supports IRSA-based temporary credentials and keeps production data secure with redaction and whitelist-based query validation.

Available tools

execute_query

Run ad-hoc SELECT queries with validation to ensure only read-only operations are executed.

execute_template

Run registered templates with validated parameters to generate reports or summaries.

list_tables

List available Athena tables to help users discover data sources.

get_table_schema

Retrieve the CREATE TABLE statement for a given table, showing its schema.