AWS Athena MCP Server

Un servidor MCP para consultar e interactuar con AWS Athena.

Documentación

Servidor MCP de AWS Athena

Un servidor MCP (Protocolo de Contexto de Modelo) simple y limpio para la integración con AWS Athena. Ejecuta consultas SQL, descubre esquemas y gestiona ejecuciones de consultas a través de una interfaz estandarizada.

✨ Características

Configuración Simple - Funcionando en menos de 5 minutos
Arquitectura Limpia - Modular, bien probada y fácil de entender
Herramientas Esenciales - Ejecución de consultas y descubrimiento de esquemas
Seguridad de Tipos - Sugerencias de tipos completas y modelos Pydantic
Soporte Asíncrono - Diseñado para rendimiento con async/await
Buenos Valores Predeterminados - Funciona de inmediato con configuración mínima

🚀 Inicio 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

Establece las variables de entorno requeridas:

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

# 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

¡Eso es todo! El servidor ahora está en ejecución y listo para aceptar conexiones MCP.

🤖 Integración con Claude Desktop

Para usar este servidor MCP con Claude Desktop:

1. Instalar Claude Desktop

Descarga e instala Claude Desktop si aún no lo has hecho.

2. Configurar Claude Desktop

Agrega la siguiente configuración a tu claude_desktop_config.json:

Ubicación del archivo de configuración:

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

Configuración (Opción 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"
      }
    }
  }
}

Configuración (Opción 2 - Usando herramienta 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"
      }
    }
  }
}

Configuración (Opción 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"
      }
    }
  }
}

Enfoque recomendado: Usa la Opción 1 (uvx) para el patrón de configuración MCP más común. La Opción 2 (herramienta instalada) ofrece mejor rendimiento ya que evita la resolución de paquetes en cada inicio.

3. Establecer Credenciales de AWS

Configura tus credenciales de AWS usando uno de estos 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 Claude Desktop

Reinicia Claude Desktop para cargar la nueva configuración del servidor MCP.

5. Verificar la Conexión

En Claude Desktop, ahora deberías poder:

Ejecutar consultas SQL contra tus bases de datos de Athena
Listar tablas y describir esquemas
Obtener resultados y estado de consultas

Ejemplo de conversación:

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]

🛠️ Configuración Automatizada (Alternativa)

Para una configuración más fácil, puedes usar el script de configuración incluido:

# 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

El script:

Verificará si uv está instalado
Te guiará a través de la configuración
Actualizará tu archivo de configuración de Claude Desktop
Verificará las credenciales de AWS
Proporcionará los siguientes pasos

También puedes copiar la configuración de ejemplo:

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

🔧 Configuración

El servidor usa variables de entorno para la configuración:

Variable	Requerida	Predeterminado	Descripción
`ATHENA_S3_OUTPUT_LOCATION`	✅	-	Ruta S3 para resultados de consultas
`AWS_REGION`	❌	`us-east-1`	Región de AWS
`ATHENA_WORKGROUP`	❌	`None`	Grupo de trabajo de Athena
`ATHENA_TIMEOUT_SECONDS`	❌	`60`	Tiempo de espera de consultas

Credenciales de AWS

Configura las credenciales de AWS usando cualquiera de estos 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

🔒 Seguridad

Variables de Entorno

⚠️ ¡NUNCA confirmes credenciales en el control de versiones!

Usa el archivo de ejemplo proporcionado para configurar tu entorno:

# 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

Mejores Prácticas para Credenciales de AWS

Usa Roles de IAM (recomendado para producción):

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

Usa perfiles de AWS CLI (recomendado para desarrollo):

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

Usa credenciales temporales cuando sea posible:

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

Evita claves de acceso de largo plazo en variables de entorno

Permisos de AWS Requeridos

Tus credenciales de AWS necesitan estos permisos mínimos:

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

Protección contra Inyección SQL

El servidor incluye protección integrada contra inyección SQL:

Validación de consultas - Los patrones peligrosos están bloqueados
Sanitización de entradas - Los nombres de bases de datos/tablas están validados
Límites de tamaño de consultas - Previene el agotamiento de recursos
Consultas parametrizadas - Cuando sea posible

Seguridad de Red

Para implementaciones de producción:

Usa endpoints de VPC para servicios de AWS
Restringe el acceso de red al servidor MCP
Usa TLS para todas las comunicaciones
Monitorea y registra todas las consultas

Monitoreo y Auditoría

Habilita el registro de CloudTrail para Athena:

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

🛠️ Herramientas Disponibles

El servidor proporciona estas herramientas MCP:

Ejecución de Consultas

run_query - Ejecuta consultas SQL contra Athena
get_status - Verifica el estado de ejecución de consultas
get_result - Obtiene resultados para consultas completadas

Descubrimiento de Esquemas

list_tables - Lista todas las tablas en una base de datos
describe_table - Obtiene el esquema detallado de una tabla

📖 Ejemplos de Uso

Ejecución Básica de Consultas

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

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

Manejo de Tiempos de Espera

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

🧪 Pruebas

Prueba tu configuración:

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

# Run the test suite
pytest

# Run with coverage
pytest --cov=athena_mcp

🏗️ Desarrollo

Configurar el Entorno de Desarrollo

# 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

Estructura del Proyecto

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

Agregar Nuevas Herramientas

Crea funciones de herramientas en src/tools/
Regístralas en el módulo apropiado
Agrega pruebas en tests/
Actualiza la documentación

Ejemplo:

# 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

🔍 Solución de Problemas

Problemas Comunes

Error de Configuración

❌ Configuration error: ATHENA_S3_OUTPUT_LOCATION environment variable is required

Solución: Establece la variable de entorno requerida:

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

Error de Credenciales de AWS

❌ AWS credentials error: AWS credentials not found

Solución: Configura las credenciales de AWS (consulta la sección de Configuración)

Permiso Denegado

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

Solución: Asegúrate de que tus credenciales de AWS tengan estos permisos:

athena:StartQueryExecution
athena:GetQueryExecution
athena:GetQueryResults
athena:ListWorkGroups
s3:GetObject, s3:PutObject en tu bucket de S3

Modo de Depuración

Habilita el registro de depuración:

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

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lee nuestras pautas de contribución y:

Haz un fork del repositorio
Crea una rama de características
Realiza tus cambios
Agrega pruebas
Envía una solicitud de extracción

📞 Soporte

Problemas: Problemas de GitHub
Discusiones: Discusiones de GitHub
Documentación: docs/

Hecho con ❤️ para la comunidad MCP