Athena MCP Server

A remote Model Context Protocol server for AWS Athena, deployed as a Docker container.

Customers connect Claude Desktop (or any MCP client) directly to this server using their own AWS IAM credentials — no local installation required.

Architecture

Claude Desktop  ──HTTP POST /mcp──►  athena-mcp-server  ──►  AWS Athena
                  (credentials in headers)

The server is fully stateless. Each request carries credentials in HTTP headers; no sessions, no credential caching.

MCP Tools

Tool	Description
`run_query`	Execute a SQL query (waits up to `timeoutMs`, returns results or polling ID)
`get_status`	Poll the status of a running query
`get_result`	Fetch results of a completed query
`list_saved_queries`	List named queries in the workgroup
`run_saved_query`	Execute a named query by ID

HTTP Headers

Every request to POST /mcp must include:

Header	Required	Default	Description
`x-aws-access-key-id`	✅	—	AWS Access Key ID
`x-aws-secret-access-key`	✅	—	AWS Secret Access Key
`x-s3-output-path`	✅	—	S3 path for query results, e.g. `s3://bucket/prefix/`
`x-aws-region`	—	`us-east-1`	AWS region
`x-aws-session-token`	—	—	Session token (temporary credentials)
`x-athena-workgroup`	—	`primary`	Athena workgroup

Missing required headers → 401 Unauthorized.

Running locally

Prerequisites

Docker + Docker Compose
AWS credentials with the required IAM permissions (see below)

Build and run

docker compose up --build

The server starts on http://localhost:3000.

Smoke test

# Health check
curl http://localhost:3000/health
# → {"status":"ok"}

# Run a query
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "x-aws-access-key-id: AKIA..." \
  -H "x-aws-secret-access-key: ..." \
  -H "x-aws-region: us-east-1" \
  -H "x-s3-output-path: s3://my-bucket/athena-results/" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "run_query",
      "arguments": {
        "database": "default",
        "query": "SELECT 1 AS test"
      }
    }
  }'

Configuring Claude Desktop

Add the following to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "teramot-athena": {
      "type": "http",
      "url": "https://athena-mcp.teramot.com/mcp",
      "headers": {
        "x-aws-access-key-id": "AKIA...",
        "x-aws-secret-access-key": "...",
        "x-aws-region": "us-east-1",
        "x-athena-workgroup": "primary",
        "x-s3-output-path": "s3://customer-bucket/athena-results/"
      }
    }
  }
}

Replace the URL with your deployed server URL and fill in the customer's credentials.

Deploying to AWS ECS

1. Push the image to ECR

AWS_ACCOUNT_ID=123456789012
AWS_REGION=us-east-1
REPO=athena-mcp-server

aws ecr create-repository --repository-name $REPO --region $AWS_REGION

aws ecr get-login-password --region $AWS_REGION \
  | docker login --username AWS --password-stdin \
    $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com

docker build -t $REPO .
docker tag $REPO:latest $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$REPO:latest
docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$REPO:latest

2. Create an ECS task definition

CPU / Memory: 256 CPU / 512 MB is sufficient for most workloads
Port mappings: container port 3000
Environment variables: none required (all config comes via headers)
Health check: CMD-SHELL wget -qO- http://localhost:3000/health || exit 1

3. Create an ECS service

Use Fargate launch type for zero infrastructure management
Attach to an Application Load Balancer (ALB) on HTTPS port 443
Enable HTTPS on the ALB listener with an ACM certificate
Target group: HTTP, port 3000, health check path /health

4. (Optional) Custom domain

Create a Route 53 alias record pointing to the ALB, e.g. athena-mcp.teramot.com.

Required IAM permissions

The customer's IAM credentials must have the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AthenaAccess",
      "Effect": "Allow",
      "Action": [
        "athena:StartQueryExecution",
        "athena:GetQueryExecution",
        "athena:GetQueryResults",
        "athena:ListNamedQueries",
        "athena:GetNamedQuery",
        "athena:ListWorkGroups"
      ],
      "Resource": "*"
    },
    {
      "Sid": "S3ResultsBucket",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::customer-results-bucket",
        "arn:aws:s3:::customer-results-bucket/*"
      ]
    },
    {
      "Sid": "GlueMetastore",
      "Effect": "Allow",
      "Action": [
        "glue:GetDatabase",
        "glue:GetDatabases",
        "glue:GetTable",
        "glue:GetTables"
      ],
      "Resource": "*"
    }
  ]
}

Replace customer-results-bucket with the actual S3 bucket name.

Development

npm install
npm run dev        # run with ts-node (hot-reload not included)
npm run build      # compile TypeScript → dist/
npm run typecheck  # type-check without emitting