@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
- Parameters:
-
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)
- Parameters:
-
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
- Parameters:
-
list_saved_queries: List all saved (named) queries in Athena. -
Returns:
- An array of saved queries with
id,name, and optionaldescription - Queries are returned from the configured
ATHENA_WORKGROUPandAWS_REGION
- An array of saved queries with
-
run_saved_query: Run a previously saved query by its ID.
-
Parameters:
namedQueryId: ID of the saved querydatabaseOverride: Optional override of the saved query's default databasemaxRows: 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
- Same behavior as
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_WORKGROUPandAWS_REGION
License
MIT