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 products by sales this month" 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](https://glama.ai/blog/2025-07-08-how-to-install-and-use-mcp-servers).

AWS Athena MCP Server

A simple, clean MCP (Model Context Protocol) server for AWS Athena integration. Execute SQL queries, discover schemas, and manage query executions through a standardized interface.

✨ Features

Simple Setup - Get running in under 5 minutes
Clean Architecture - Modular, well-tested, easy to understand
Essential Tools - Query execution and schema discovery
Type Safe - Full type hints and Pydantic models
Async Support - Built for performance with async/await
Good Defaults - Works out of the box with minimal configuration

🚀 Quick Start

1. Install

# From PyPI with uv (recommended for Claude Desktop) uv tool install aws-athena-mcp # From PyPI with pip pip install aws-athena-mcp # Or from source git clone https://github.com/ColeMurray/aws-athena-mcp cd aws-athena-mcp pip install -e .

2. Configure

Set the required environment variables:

# Required export ATHENA_S3_OUTPUT_LOCATION=s3://your-bucket/athena-results/ # Optional (with defaults) export AWS_REGION=us-east-1 export ATHENA_WORKGROUP=primary export ATHENA_TIMEOUT_SECONDS=60

3. Run

# Start the MCP server (if installed with uv tool install) aws-athena-mcp # Or run directly with uv (without installing) uv tool run aws-athena-mcp # Or run directly with uvx (without installing) uvx aws-athena-mcp # Or run directly with Python python -m athena_mcp.server

That's it! The server is now running and ready to accept MCP connections.

🤖 Claude Desktop Integration

To use this MCP server with Claude Desktop:

1. Install Claude Desktop

Download and install Claude Desktop if you haven't already.

2. Configure Claude Desktop

Add the following configuration to your claude_desktop_config.json:

Location of config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration (Option 1 - Using uvx - Recommended):

{ "mcpServers": { "aws-athena-mcp": { "command": "uvx", "args": [ "aws-athena-mcp" ], "env": { "ATHENA_S3_OUTPUT_LOCATION": "s3://your-bucket/athena-results/", "AWS_REGION": "us-east-1", "ATHENA_WORKGROUP": "primary", "ATHENA_TIMEOUT_SECONDS": "60" } } } }

Configuration (Option 2 - Using installed tool):

{ "mcpServers": { "aws-athena-mcp": { "command": "aws-athena-mcp", "env": { "ATHENA_S3_OUTPUT_LOCATION": "s3://your-bucket/athena-results/", "AWS_REGION": "us-east-1", "ATHENA_WORKGROUP": "primary", "ATHENA_TIMEOUT_SECONDS": "60" } } } }

Configuration (Option 3 - Using uv tool run):

{ "mcpServers": { "aws-athena-mcp": { "command": "uv", "args": [ "tool", "run", "aws-athena-mcp" ], "env": { "ATHENA_S3_OUTPUT_LOCATION": "s3://your-bucket/athena-results/", "AWS_REGION": "us-east-1", "ATHENA_WORKGROUP": "primary", "ATHENA_TIMEOUT_SECONDS": "60" } } } }

Recommended approach: Use Option 1 (uvx) for the most common MCP setup pattern. Option 2 (installed tool) offers better performance as it avoids package resolution on each startup.

3. Set AWS Credentials

Configure your AWS credentials using one of these methods:

# Method 1: Environment variables (add to your shell profile) export AWS_ACCESS_KEY_ID=your-access-key export AWS_SECRET_ACCESS_KEY=your-secret-key # Method 2: AWS CLI aws configure # Method 3: AWS Profile export AWS_PROFILE=your-profile

4. Restart Claude Desktop

Restart Claude Desktop to load the new MCP server configuration.

5. Verify Connection

In Claude Desktop, you should now be able to:

Execute SQL queries against your Athena databases
List tables and describe schemas
Get query results and status

Example conversation:

You: "List all tables in my 'analytics' database" Claude: I'll help you list the tables in your analytics database using the Athena MCP server. [Uses list_tables tool]

🛠️ Automated Setup (Alternative)

For easier setup, you can use the included setup script:

# Clone the repository git clone https://github.com/ColeMurray/aws-athena-mcp cd aws-athena-mcp # Run the setup script python scripts/setup_claude_desktop.py

The script will:

Check if uv is installed
Guide you through configuration
Update your Claude Desktop config file
Verify AWS credentials
Provide next steps

You can also copy the example configuration:

cp examples/claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json # Then edit the file to add your S3 bucket and AWS settings

🔧 Configuration

The server uses environment variables for configuration:

Variable	Required	Default	Description
`ATHENA_S3_OUTPUT_LOCATION`	✅	-	S3 path for query results
`AWS_REGION`	❌	`us-east-1`	AWS region
`ATHENA_WORKGROUP`	❌	`None`	Athena workgroup
`ATHENA_TIMEOUT_SECONDS`	❌	`60`	Query timeout

AWS Credentials

Configure AWS credentials using any of these methods:

# Method 1: Environment variables export AWS_ACCESS_KEY_ID=your-access-key export AWS_SECRET_ACCESS_KEY=your-secret-key # Method 2: AWS CLI aws configure # Method 3: AWS Profile export AWS_PROFILE=your-profile # Method 4: IAM roles (for EC2/Lambda) # No configuration needed

🔒 Security

Environment Variables

⚠️ NEVER commit credentials to version control!

Use the provided example file to set up your environment:

# Copy the example file cp examples/environment_variables.example .env # Edit with your values nano .env # Make sure .env is in .gitignore (it already is) echo ".env" >> .gitignore

AWS Credentials Best Practices

Use IAM Roles (recommended for production):
# No credentials needed - uses instance/container role export ATHENA_S3_OUTPUT_LOCATION=s3://your-bucket/results/
Use AWS CLI profiles (recommended for development):
aws configure --profile athena-mcp export AWS_PROFILE=athena-mcp
Use temporary credentials when possible:
aws sts assume-role --role-arn arn:aws:iam::123456789012:role/AthenaRole \ --role-session-name athena-mcp-session
Avoid long-term access keys in environment variables

Required AWS Permissions

Your AWS credentials need these minimum permissions:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "athena:StartQueryExecution", "athena:GetQueryExecution", "athena:GetQueryResults", "athena:ListWorkGroups", "athena:GetWorkGroup" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::your-bucket/athena-results/*" }, { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::your-bucket" }, { "Effect": "Allow", "Action": [ "glue:GetDatabase", "glue:GetDatabases", "glue:GetTable", "glue:GetTables" ], "Resource": "*" } ] }

SQL Injection Protection

The server includes built-in SQL injection protection:

Query validation - Dangerous patterns are blocked
Input sanitization - Database/table names are validated
Query size limits - Prevents resource exhaustion
Parameterized queries - When possible

Network Security

For production deployments:

Use VPC endpoints for AWS services
Restrict network access to the MCP server
Use TLS for all communications
Monitor and log all queries

Monitoring and Auditing

Enable CloudTrail logging for Athena:

{ "eventVersion": "1.05", "userIdentity": {...}, "eventTime": "2024-01-01T12:00:00Z", "eventSource": "athena.amazonaws.com", "eventName": "StartQueryExecution", "resources": [...] }

🛠️ Available Tools

The server provides these MCP tools:

Query Execution

run_query - Execute SQL queries against Athena
get_status - Check query execution status
get_result - Get results for completed queries

Schema Discovery

list_tables - List all tables in a database
describe_table - Get detailed table schema

📖 Usage Examples

Basic Query Execution

# Using the MCP client (pseudo-code) result = await mcp_client.call_tool("run_query", { "database": "default", "query": "SELECT * FROM my_table LIMIT 10", "max_rows": 10 })

Schema Discovery

# List tables tables = await mcp_client.call_tool("list_tables", { "database": "default" }) # Describe a table schema = await mcp_client.call_tool("describe_table", { "database": "default", "table_name": "my_table" })

Handling Timeouts

# Long-running query result = await mcp_client.call_tool("run_query", { "database": "default", "query": "SELECT COUNT(*) FROM large_table" }) if "query_execution_id" in result: # Query timed out, check status later status = await mcp_client.call_tool("get_status", { "query_execution_id": result["query_execution_id"] })

🧪 Testing

Test your configuration:

# Test configuration and AWS connection python scripts/test_connection.py # Run the test suite pytest # Run with coverage pytest --cov=athena_mcp

🏗️ Development

Setup Development Environment

# Clone and install in development mode git clone https://github.com/ColeMurray/aws-athena-mcp cd aws-athena-mcp pip install -e ".[dev]" # Run tests pytest # Format code black src tests isort src tests # Type checking mypy src

Project Structure

aws-athena-mcp/ ├── src/athena_mcp/ # Main package │ ├── server.py # MCP server │ ├── athena.py # AWS Athena client │ ├── config.py # Configuration │ └── models.py # Data models ├── src/tools/ # MCP tools │ ├── query.py # Query tools │ └── schema.py # Schema tools ├── tests/ # Test suite ├── examples/ # Usage examples ├── scripts/ # Utility scripts └── docs/ # Documentation

Adding New Tools

Create tool functions in src/tools/
Register them in the appropriate module
Add tests in tests/
Update documentation

Example:

# In src/tools/query.py def register_query_tools(mcp, athena_client): @mcp.tool() async def my_new_tool(param: str) -> str: """My new tool description.""" # Implementation here return result

🔍 Troubleshooting

Common Issues

Configuration Error

❌ Configuration error: ATHENA_S3_OUTPUT_LOCATION environment variable is required

Solution: Set the required environment variable:

export ATHENA_S3_OUTPUT_LOCATION=s3://your-bucket/results/

AWS Credentials Error

❌ AWS credentials error: AWS credentials not found

Solution: Configure AWS credentials (see Configuration section)

Permission Denied

❌ AWS credentials error: AWS credentials are invalid or insufficient permissions

Solution: Ensure your AWS credentials have these permissions:

athena:StartQueryExecution
athena:GetQueryExecution
athena:GetQueryResults
athena:ListWorkGroups
s3:GetObject, s3:PutObject on your S3 bucket

Debug Mode

Enable debug logging:

export PYTHONPATH=src python -c " import logging logging.basicConfig(level=logging.DEBUG) from athena_mcp.server import main main() "

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions welcome! Please read our contributing guidelines and:

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

Made with ❤️ for the MCP community

AWS Athena MCP Server

✨ Features

🚀 Quick Start

1. Install

2. Configure

3. Run

🤖 Claude Desktop Integration

1. Install Claude Desktop

2. Configure Claude Desktop

3. Set AWS Credentials

4. Restart Claude Desktop

5. Verify Connection

🛠️ Automated Setup (Alternative)

🔧 Configuration

AWS Credentials

🔒 Security

Environment Variables

AWS Credentials Best Practices

Required AWS Permissions

SQL Injection Protection

Network Security

Monitoring and Auditing

🛠️ Available Tools

Query Execution

Schema Discovery

📖 Usage Examples

Basic Query Execution

Schema Discovery

Handling Timeouts

🧪 Testing

🏗️ Development

Setup Development Environment

Project Structure

Adding New Tools

🔍 Troubleshooting

Common Issues

Debug Mode

📄 License

🤝 Contributing

📞 Support

Resources

New MCP Servers

Latest Blog Posts

MCP directory API