aws-athena-mcp

AWS Athena MCP using FastMCP

23 stars PythonOthers Updated Sep 4, 2026

Documentation

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

bash

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

bash

# 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

bash

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

json

{
  "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):

json

{
  "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):

json

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

bash

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

code

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:

bash

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

bash

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:

bash

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

bash

# 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

1. Use IAM Roles (recommended for production):

bash

# No credentials needed - uses instance/container role
   export ATHENA_S3_OUTPUT_LOCATION=s3://your-bucket/results/

2. Use AWS CLI profiles (recommended for development):

bash

aws configure --profile athena-mcp
   export AWS_PROFILE=athena-mcp

3. Use temporary credentials when possible:

bash

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

4. Avoid long-term access keys in environment variables

Required AWS Permissions

Your AWS credentials need these minimum permissions:

json

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

json

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

python

# 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

python

# 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

python

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

bash

# 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

bash

# 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

code

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

1. Create tool functions in `src/tools/`

2. Register them in the appropriate module

3. Add tests in `tests/`

4. Update documentation

Example:

python

# 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

code

❌ Configuration error: ATHENA_S3_OUTPUT_LOCATION environment variable is required

Solution: Set the required environment variable:

bash

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

AWS Credentials Error

code

❌ AWS credentials error: AWS credentials not found

Solution: Configure AWS credentials (see Configuration section)

Permission Denied

code

❌ 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:

bash

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:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests

5. Submit a pull request

📞 Support

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

Made with ❤️ for the MCP community

Frequently asked questions

What is aws-athena-mcp?

aws-athena-mcp is AWS Athena MCP using FastMCP

How do I install aws-athena-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is aws-athena-mcp open source?

Yes — it is hosted on GitHub at https://github.com/ColeMurray/aws-athena-mcp and has 23 stars.

Related MCP tools

cognee

Cognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.

30,433 Python

agent-memoryagent-skillsai+16

skyvern

Automate browser based workflows with AI

22,930 Python

apiautomationbrowser+13

hindsight

Hindsight: Agent Memory That Learns

22,468 Python

agentic-aimemoryagents+1

watermarks-remover

A privacy-first app that strips AI watermarks from content you own.

20,504 Python

agent-skillaic2pa+12

Qwen-Agent

Agent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.

17,062 Python

pal-mcp-server

The power of Claude Code / GeminiCLI / CodexCLI + [Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / Custom Model / All Of The Above] working as one.

11,731 Python

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP