Skip to main content
Glama

AthenaMCPServer

An MCP (Model Context Protocol) server for querying Amazon Athena. This server allows AI assistants to execute SQL queries against AWS Athena and retrieve results in a structured format.

Features

  • Execute SQL queries against Amazon Athena

  • Authenticate to AWS account using profiles

  • Format results as JSON, CSV, or formatted tables

  • Configurable database, region, and output location

Related MCP server: NLSQL MCP Server

Setup

# Install dependencies
npm install

Configuration

The server uses the following environment variables for configuration:

  • AWS_REGION: AWS region where Athena is located (default: "us-east-1")

  • ATHENA_WORKGROUP: Athena workgroup to use (default: "primary")

  • ATHENA_OUTPUT_LOCATION: S3 location for query results (default: "s3://aws-athena-query-results/")

  • ATHENA_DATABASE: Default database to query (default: "default")

  • ATHENA_CATALOG: Default catalog/data source to query (default: "AwsDataCatalog")

  • AWS_PROFILE: AWS Profile to use for authentication (default: undefined, and will fallback to using default AWS credentials provider chain)

You can set these environment variables before running the server:

export AWS_REGION=us-west-2
export ATHENA_WORKGROUP=my-workgroup
export ATHENA_OUTPUT_LOCATION=s3://my-bucket/athena-results/
export ATHENA_DATABASE=my_database
export ATHENA_CATALOG=AwsDataCatalog
export AWS_PROFILE=aws_profile_name

Alternatively, you can set these environment variables in the MCP Client configuration (see below).

Configuration for MCP Client

{
  "mcpServers": {
    "athena-mcp": {
      "command": "npm",
      "args": [
        "--prefix",
        "/Users/<alias>/workplace/AthenaMCPServer/src/AthenaMCPServer",
        "start"
      ],
      "disabled": false,
      "env": {
        "AWS_PROFILE": "<aws-profile-for-account-with-athena>",
        "ATHENA_OUTPUT_LOCATION": "s3://<your-athena-query-results-bucket>"
      },
      "autoApprove": []
    }
  }
}

AWS Authentication

The server uses the AWS SDK's default credential provider chain. You can authenticate using any of the following methods:

  1. Environment variables (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)

  2. Shared credentials file (~/.aws/credentials)

  3. EC2 instance profile or ECS task role

  4. AWS SSO

Using AWS Profiles

You can specify an AWS profile from your shared credentials config file (~/.aws/config) when executing queries:

{
  "query": "SELECT * FROM my_table LIMIT 10",
  "profile": "my-aws-profile"
}

This is useful when you have multiple AWS accounts or roles configured in your credentials file.

For more information, see the AWS SDK documentation.

Usage

Basic example Using MCP Client (e.g. Cline)

Type the following into the MCP Client Window

use the athena mcp server to run a basic query and return in csv

Response:

test
1

You can pass it a query directly, or use other LLMs to generate the SQL for you and ask it to run it using the Athena MCP Server

Starting the Server

# Start the server
npm start

Available Tools

query_athena

Executes SQL queries against Amazon Athena and retrieves results.

Parameters:

  • query (required): SQL query to execute

  • database (optional): Database to query (uses default if not specified)

  • catalog (optional): Catalog (Data source) to query (uses AwsDataCatalog if not specified)

  • region (optional): AWS region (uses default if not specified)

  • format (optional): Result format (json, table, or csv)

  • profile (optional): AWS profile name to use from shared credentials file

Example:

{
  "query": "SELECT * FROM my_table LIMIT 10",
  "database": "my_database",
  "catalog": "AwsDataCatalog",
  "format": "table",
  "profile": "my-aws-profile"
}

Development

Project Structure

athena-mcp/
├── src/
│   ├── core/
│   │   └── aws/
│   │       └── athena-client.ts
│   ├── tools/
│   │   └── query-athena/
│   │       └── tool.ts
│   ├── cli.ts
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md

Running in Development Mode

# Run in development mode with auto-reload
npm run watch

Testing

# Run tests
npm test

Available Tools

1 tool
query_athenaB

Execute SQL queries against Amazon Athena and retrieve results

Inputs: query (required), format, region, catalog, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of overlap or confusion. The tool's purpose is clearly defined as executing SQL queries and retrieving results.

    Naming Consistency5/5

    The name 'query_athena' follows a clear verb_noun pattern with snake_case. While there is only one tool, the name is consistent with common MCP naming conventions and unambiguous.

    Tool Count3/5

    A single tool feels thin for a server dedicated to Athena, though the narrow purpose of querying makes it borderline acceptable. It falls short of the typical well-scoped 3-15 tool range.

    Completeness4/5

    The tool covers the core workflow of executing queries and retrieving results, but lacks explicit operations like query cancellation or schema listing. These can potentially be handled via SQL, representing minor gaps rather than fatal omissions.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An open-source MCP server that connects to various data sources (SQL databases, CSV, Parquet files), allowing AI models to execute SQL queries and generate data visualizations for analytics and business intelligence.
      12
      75
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP (Model Context Protocol) server that exposes natural language to SQL functionality, allowing any MCP-compatible client to convert plain English questions into SQL queries for database interaction using AI.
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to query databases, execute SQL, and manage Metabase resources like dashboards, cards, and collections through natural language.
      22
      MIT
    • -
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that bridges AI assistants with SQL databases, enabling natural language querying across multiple database types with built-in optimization and security.
      3
      -