AWS Athena MCP Server

Um servidor MCP para consultar e interagir com AWS Athena.

Documentação

AWS Athena MCP Server

Um servidor MCP (Model Context Protocol) simples e limpo para integração com AWS Athena. Execute consultas SQL, descubra esquemas e gerencie execuções de consultas através de uma interface padronizada.

✨ Recursos

Configuração Simples - Funcionando em menos de 5 minutos
Arquitetura Limpa - Modular, bem testada, fácil de entender
Ferramentas Essenciais - Execução de consultas e descoberta de esquemas
Segurança de Tipos - Anotações de tipo completas e modelos Pydantic
Suporte Assíncrono - Construído para desempenho com async/await
Boas Configurações Padrão - Funciona imediatamente com configuração mínima

🚀 Início Rápido

1. Instalar

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

Defina as variáveis de ambiente necessárias:

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

# 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

Pronto! O servidor está agora em execução e pronto para aceitar conexões MCP.

🤖 Integração com Claude Desktop

Para usar este servidor MCP com o Claude Desktop:

1. Instalar o Claude Desktop

Baixe e instale o Claude Desktop se ainda não o fez.

2. Configurar o Claude Desktop

Adicione a seguinte configuração ao seu claude_desktop_config.json:

Localização do arquivo de configuração:

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

Configuração (Opção 1 - Usando uvx - Recomendado):

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

Configuração (Opção 2 - Usando ferramenta instalada):

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

Configuração (Opção 3 - Usando 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"
      }
    }
  }
}

Abordagem recomendada: Use a Opção 1 (uvx) para o padrão de configuração MCP mais comum. A Opção 2 (ferramenta instalada) oferece melhor desempenho, pois evita a resolução de pacotes a cada inicialização.

3. Definir Credenciais AWS

Configure suas credenciais AWS usando um destes métodos:

# 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. Reiniciar o Claude Desktop

Reinicie o Claude Desktop para carregar a nova configuração do servidor MCP.

5. Verificar a Conexão

No Claude Desktop, você agora deve ser capaz de:

Executar consultas SQL nos seus bancos de dados Athena
Listar tabelas e descrever esquemas
Obter resultados e status de consultas

Exemplo de conversa:

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]

🛠️ Configuração Automatizada (Alternativa)

Para uma configuração mais fácil, você pode usar o script de configuração incluído:

# 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

O script irá:

Verificar se o uv está instalado
Orientar você durante a configuração
Atualizar seu arquivo de configuração do Claude Desktop
Verificar as credenciais AWS
Fornecer próximos passos

Você também pode copiar a configuração de exemplo:

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

🔧 Configuração

O servidor usa variáveis de ambiente para configuração:

Variável	Obrigatória	Padrão	Descrição
`ATHENA_S3_OUTPUT_LOCATION`	✅	-	Caminho S3 para resultados de consultas
`AWS_REGION`	❌	`us-east-1`	Região AWS
`ATHENA_WORKGROUP`	❌	`None`	Grupo de trabalho Athena
`ATHENA_TIMEOUT_SECONDS`	❌	`60`	Tempo limite de consulta

Credenciais AWS

Configure as credenciais AWS usando qualquer um destes métodos:

# 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

🔒 Segurança

Variáveis de Ambiente

⚠️ NUNCA envie credenciais para o controle de versão!

Use o arquivo de exemplo fornecido para configurar seu ambiente:

# 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

Boas Práticas para Credenciais AWS

Use IAM Roles (recomendado para produção):

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

Use perfis da AWS CLI (recomendado para desenvolvimento):

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

Use credenciais temporárias quando possível:

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

Evite chaves de acesso de longo prazo em variáveis de ambiente

Permissões AWS Necessárias

Suas credenciais AWS precisam destas permissões mínimas:

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

Proteção contra Injeção de SQL

O servidor inclui proteção integrada contra injeção de SQL:

Validação de consultas - Padrões perigosos são bloqueados
Sanitização de entrada - Nomes de bancos de dados/tabelas são validados
Limites de tamanho de consulta - Previne esgotamento de recursos
Consultas parametrizadas - Quando possível

Segurança de Rede

Para implantações em produção:

Use endpoints VPC para serviços AWS
Restrinja o acesso de rede ao servidor MCP
Use TLS para todas as comunicações
Monitore e registre todas as consultas

Monitoramento e Auditoria

Ative o registro CloudTrail para Athena:

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

🛠️ Ferramentas Disponíveis

O servidor fornece estas ferramentas MCP:

Execução de Consultas

run_query - Executar consultas SQL no Athena
get_status - Verificar o status da execução de consultas
get_result - Obter resultados de consultas concluídas

Descoberta de Esquemas

list_tables - Listar todas as tabelas em um banco de dados
describe_table - Obter esquema detalhado de tabela

📖 Exemplos de Uso

Execução Básica de Consulta

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

Descoberta de Esquemas

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

Lidando com Tempos Limite

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

🧪 Testes

Teste sua configuração:

# Test configuration and AWS connection
python scripts/test_connection.py

# Run the test suite
pytest

# Run with coverage
pytest --cov=athena_mcp

🏗️ Desenvolvimento

Configurar Ambiente de Desenvolvimento

# 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

Estrutura do Projeto

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

Adicionando Novas Ferramentas

Crie funções de ferramenta em src/tools/
Registre-as no módulo apropriado
Adicione testes em tests/
Atualize a documentação

Exemplo:

# 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

🔍 Solução de Problemas

Problemas Comuns

Erro de Configuração

❌ Configuration error: ATHENA_S3_OUTPUT_LOCATION environment variable is required

Solução: Defina a variável de ambiente necessária:

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

Erro de Credenciais AWS

❌ AWS credentials error: AWS credentials not found

Solução: Configure as credenciais AWS (veja a seção Configuração)

Permissão Negada

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

Solução: Garanta que suas credenciais AWS tenham estas permissões:

athena:StartQueryExecution
athena:GetQueryExecution
athena:GetQueryResults
athena:ListWorkGroups
s3:GetObject, s3:PutObject no seu bucket S3

Modo de Depuração

Ative o registro de depuração:

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

📄 Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

🤝 Contribuições

Contribuições são bem-vindas! Leia nossas diretrizes de contribuição e:

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Adicione testes
Envie um pull request

📞 Suporte

Problemas: GitHub Issues
Discussões: GitHub Discussions
Documentação: docs/

Feito com ❤️ para a comunidade MCP