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.

- 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

# 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 .

# 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

# 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.

To use this MCP server with Claude Desktop:

Download and installClaude Desktopif you haven't already.

{ "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.

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

Restart Claude Desktop to load the new MCP server configuration.

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

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]

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

- 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

The server uses environment variables for configuration:

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

⚠️ 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

-

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 credentialswhen possible:

aws sts assume-role --role-arn arn:aws:iam::123456789012:role/AthenaRole \ --role-session-name athena-mcp-session

Avoid long-term access keysin environment variables

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": "" } ] }

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

# 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 })

# 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" })

# 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"] })

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

# 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

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

- Create tool functions insrc/tools/
- Register them in the appropriate module
- Add tests intests/
- Update documentation

# 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

❌ 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 not found

Solution: Configure AWS credentials (see Configuration section)

❌ 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:PutObjecton your S3 bucket

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

MIT License - seeLICENSEfile for details.

Contributions welcome! Please read ourcontributing guidelinesand:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request

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

Interact with AWS Amplify Gen2 data models using natural language and Cognito authentication.