How do I use AWS Athena MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AWS Athena MCP Server show me the top 10 customers by total sales from the orders table" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

@lishenxydlgzs/aws-athena-mcp

A Model Context Protocol (MCP) server for running AWS Athena queries. This server enables AI assistants to execute SQL queries against your AWS Athena databases and retrieve results.

Features:

Execute SQL queries via AWS Athena
Support for both stdio (local) and Lambda + API Gateway (remote) deployment
OAuth 2.0 authentication via AWS Cognito (Lambda deployment)
Async query execution with status polling
Named query support

Deployment Options

Option 1: Local (stdio) - For MCP Clients

Use with Claude Desktop, Cline, or other MCP clients:

Option 1: Local (stdio) - For MCP Clients

Use with Claude Desktop, Cline, or other MCP clients:

Configure AWS credentials using one of the following methods:
- AWS CLI configuration
- Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
- IAM role (if running on AWS)
Add the server to your MCP configuration:

{ "mcpServers": { "athena": { "command": "npx", "args": ["-y", "@lishenxydlgzs/aws-athena-mcp"], "env": { // Required "OUTPUT_S3_PATH": "s3://your-bucket/athena-results/", // Optional AWS configuration "AWS_REGION": "us-east-1", // Default: AWS CLI default region "AWS_PROFILE": "default", // Default: 'default' profile "AWS_ACCESS_KEY_ID": "", // Optional: AWS access key "AWS_SECRET_ACCESS_KEY": "", // Optional: AWS secret key "AWS_SESSION_TOKEN": "", // Optional: AWS session token // Optional server configuration "ATHENA_WORKGROUP": "default_workgroup", // Optional: specify the Athena WorkGroup "QUERY_TIMEOUT_MS": "300000", // Default: 5 minutes (300000ms) "MAX_RETRIES": "100", // Default: 100 attempts "RETRY_DELAY_MS": "500" // Default: 500ms between retries } } } }

Option 2: Lambda + API Gateway - For Remote Access

Deploy as a serverless API with OAuth 2.0 authentication:

# 首次部署（交互式配置） ./deploy.sh # 或快速部署（使用已有配置） ./deploy-quick.sh

部署脚本会自动：

构建 TypeScript 代码
使用 SAM 部署到 AWS
创建 Cognito User Pool 和 App Client
配置 API Gateway OAuth 认证
输出完整的 OAuth 配置信息（包括 Client Secret）
保存配置到 .env.oauth 文件

部署后输出示例：

================================================ 🎉 部署配置信息 ================================================ 📡 API 端点: https://xxxxx.execute-api.us-east-1.amazonaws.com/prod/mcp 🔐 OAuth 认证配置: Client ID: xxxxxxxxxxxxxxxxxxxxx Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Token URL: https://xxxxx.auth.us-east-1.amazoncognito.com/oauth2/token Scopes: athena-mcp-api/read athena-mcp-api/write 🏢 AWS 资源: User Pool ID: us-east-1_xxxxx Function ARN: arn:aws:lambda:us-east-1:xxxxx:function:xxxxx

测试部署：

# 测试 OAuth 认证 ./test-cognito-auth.sh # 测试查询执行 ./test-oauth-query.sh "SELECT * FROM my_table LIMIT 5" "my_database"

手动获取配置（如果需要）：

# Get Client ID and Token URL from CloudFormation outputs aws cloudformation describe-stacks --stack-name aws-athena-mcp-stack \ --query "Stacks[0].Outputs" # Get Client Secret aws cognito-idp describe-user-pool-client \ --user-pool-id <USER_POOL_ID> \ --client-id <CLIENT_ID> \ --query "UserPoolClient.ClientSecret" \ --output text

Client Integration:

// See examples/oauth-client-example.ts for full implementation import { AthenaMcpClient } from './examples/oauth-client-example'; const client = new AthenaMcpClient({ clientId: process.env.COGNITO_CLIENT_ID!, clientSecret: process.env.COGNITO_CLIENT_SECRET!, tokenUrl: process.env.COGNITO_TOKEN_URL!, apiEndpoint: process.env.API_ENDPOINT!, }); await client.initialize(); const result = await client.runQuery('my_db', 'SELECT * FROM my_table LIMIT 10');

For detailed OAuth setup instructions, see OAUTH-SETUP-GUIDE.md.

Available Tools

The server provides the following tools:

run_query: Execute a SQL query using AWS Athena
- Parameters:
  - database: The Athena database to query
  - query: SQL query to execute
  - maxRows: Maximum number of rows to return (default: 1000, max: 10000)
- Returns:
  - If query completes within timeout: Full query results
  - If timeout reached: Only the queryExecutionId for later retrieval
get_status: Check the status of a query execution
- Parameters:
  - queryExecutionId: The ID returned from run_query
- Returns:
  - state: Query state (QUEUED, RUNNING, SUCCEEDED, FAILED, or CANCELLED)
  - stateChangeReason: Reason for state change (if any)
  - submissionDateTime: When the query was submitted
  - completionDateTime: When the query completed (if finished)
  - statistics: Query execution statistics (if available)
get_result: Retrieve results for a completed query
- Parameters:
  - queryExecutionId: The ID returned from run_query
  - maxRows: Maximum number of rows to return (default: 1000, max: 10000)
- Returns:
  - Full query results if the query has completed successfully
  - Error if query failed or is still running
list_saved_queries: List all saved (named) queries in Athena.
Returns:
- An array of saved queries with id, name, and optional description
- Queries are returned from the configured ATHENA_WORKGROUP and AWS_REGION
run_saved_query: Run a previously saved query by its ID.
Parameters:
- namedQueryId: ID of the saved query
- databaseOverride: Optional override of the saved query's default database
- maxRows: Maximum number of rows to return (default: 1000)
- timeoutMs: Timeout in milliseconds (default: 60000)
Returns:
- Same behavior as run_query: full results or execution ID

Usage Examples

Show All Databases

Message to AI Assistant: List all databases in Athena

MCP parameter:

{ "database": "default", "query": "SHOW DATABASES" }

List Tables in a Database

Message to AI Assistant: Show me all tables in the default database

MCP parameter:

{ "database": "default", "query": "SHOW TABLES" }

Get Table Schema

Message to AI Assistant: What's the schema of the asin_sitebestimg table?

MCP parameter:

{ "database": "default", "query": "DESCRIBE default.asin_sitebestimg" }

Table Rows Preview

Message to AI Assistant: Show some rows from my_database.mytable

MCP parameter:

{ "database": "my_database", "query": "SELECT * FROM my_table LIMIT 10", "maxRows": 10 }

Advanced Query with Filtering and Aggregation

Message to AI Assistant: Find the average price by category for in-stock products

MCP parameter:

{ "database": "my_database", "query": "SELECT category, COUNT(*) as count, AVG(price) as avg_price FROM products WHERE in_stock = true GROUP BY category ORDER BY count DESC", "maxRows": 100 }

Checking Query Status

{ "queryExecutionId": "12345-67890-abcdef" }

Getting Results for a Completed Query

{ "queryExecutionId": "12345-67890-abcdef", "maxRows": 10 }

Listing Saved Queries

{ "name": "list_saved_queries", "arguments": {} }

Running a Saved Query

{ "name": "run_saved_query", "arguments": { "namedQueryId": "abcd-1234-efgh-5678", "maxRows": 100 } }

Requirements

Node.js >= 16
AWS credentials with appropriate Athena and S3 permissions
S3 bucket for query results
Named queries (optional) must exist in the specified ATHENA_WORKGROUP and AWS_REGION

License

MIT

Repository

GitHub Repository

AWS Athena MCP Server

@lishenxydlgzs/aws-athena-mcp

Deployment Options

Option 1: Local (stdio) - For MCP Clients

Option 1: Local (stdio) - For MCP Clients

Option 2: Lambda + API Gateway - For Remote Access

Available Tools

Usage Examples

Show All Databases

List Tables in a Database

Get Table Schema

Table Rows Preview

Advanced Query with Filtering and Aggregation

Checking Query Status

Getting Results for a Completed Query

Listing Saved Queries

Running a Saved Query

Requirements

License

Repository

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API