AWS Athena

Execute consultas SQL em dados no Amazon S3 usando AWS Athena.

Documentação

@lishenxydlgzs/aws-athena-mcp

Um servidor Model Context Protocol (MCP) para executar consultas AWS Athena. Este servidor permite que assistentes de IA executem consultas SQL em seus bancos de dados AWS Athena e recuperem resultados.

Uso

Configure as credenciais AWS usando um dos seguintes métodos:
- Configuração da CLI da AWS
- Variáveis de ambiente (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
- Papel IAM (se estiver executando na AWS)
Adicione o servidor à sua configuração MCP:

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": ["-y", "@lishenxydlgzs/aws-athena-mcp"],
      "env": {
        // Required
        "OUTPUT_S3_PATH": "s3://your-bucket/athena-results/",
        
        // Optional AWS configuration
        "AWS_REGION": "us-east-1",                    // Default: AWS CLI default region
        "AWS_PROFILE": "default",                     // Default: 'default' profile
        "AWS_ACCESS_KEY_ID": "",                      // Optional: AWS access key
        "AWS_SECRET_ACCESS_KEY": "",                  // Optional: AWS secret key
        "AWS_SESSION_TOKEN": "",                      // Optional: AWS session token
        
        // Optional server configuration
        "ATHENA_WORKGROUP": "default_workgroup",      // Optional: specify the Athena WorkGroup
        "QUERY_TIMEOUT_MS": "300000",                 // Default: 5 minutes (300000ms)
        "MAX_RETRIES": "100",                         // Default: 100 attempts
        "RETRY_DELAY_MS": "500"                       // Default: 500ms between retries
      }
    }
  }
}

O servidor fornece as seguintes ferramentas:

run_query: Executa uma consulta SQL usando AWS Athena
- Parâmetros:
  - database: O banco de dados Athena a ser consultado
  - query: Consulta SQL a ser executada
  - maxRows: Número máximo de linhas a retornar (padrão: 1000, máximo: 10000)
- Retorna:
  - Se a consulta for concluída dentro do tempo limite: Resultados completos da consulta
  - Se o tempo limite for atingido: Apenas o queryExecutionId para recuperação posterior
get_status: Verifica o status de uma execução de consulta
- Parâmetros:
  - queryExecutionId: O ID retornado pelo run_query
- Retorna:
  - state: Estado da consulta (QUEUED, RUNNING, SUCCEEDED, FAILED ou CANCELLED)
  - stateChangeReason: Motivo da mudança de estado (se houver)
  - submissionDateTime: Quando a consulta foi enviada
  - completionDateTime: Quando a consulta foi concluída (se finalizada)
  - statistics: Estatísticas de execução da consulta (se disponíveis)
get_result: Recupera resultados de uma consulta concluída
- Parâmetros:
  - queryExecutionId: O ID retornado pelo run_query
  - maxRows: Número máximo de linhas a retornar (padrão: 1000, máximo: 10000)
- Retorna:
  - Resultados completos da consulta se a consulta foi concluída com sucesso
  - Erro se a consulta falhou ou ainda está em execução
list_saved_queries: Lista todas as consultas salvas (nomeadas) no Athena.
Retorna:
- Uma matriz de consultas salvas com id, name e description opcional
- As consultas são retornadas do ATHENA_WORKGROUP e AWS_REGION configurados
run_saved_query: Executa uma consulta previamente salva pelo seu ID.
Parâmetros:
- namedQueryId: ID da consulta salva
- databaseOverride: Substituição opcional do banco de dados padrão da consulta salva
- maxRows: Número máximo de linhas a retornar (padrão: 1000)
- timeoutMs: Tempo limite em milissegundos (padrão: 60000)
Retorna:
- Mesmo comportamento que run_query: resultados completos ou ID de execução

Exemplos de Uso

Mostrar Todos os Bancos de Dados

Mensagem para o Assistente de IA: List all databases in Athena

MCP parameter:

{
  "database": "default",
  "query": "SHOW DATABASES"
}

Listar Tabelas em um Banco de Dados

Mensagem para o Assistente de IA: Show me all tables in the default database

MCP parameter:

{
  "database": "default",
  "query": "SHOW TABLES"
}

Obter Esquema de Tabela

Mensagem para o Assistente de IA: What's the schema of the asin_sitebestimg table?

MCP parameter:

{
  "database": "default",
  "query": "DESCRIBE default.asin_sitebestimg"
}

Pré-visualização de Linhas da Tabela

Mensagem para o Assistente de IA: Show some rows from my_database.mytable

MCP parameter:

{
  "database": "my_database",
  "query": "SELECT * FROM my_table LIMIT 10",
  "maxRows": 10
}

Consulta Avançada com Filtragem e Agregação

Mensagem para o Assistente de IA: Find the average price by category for in-stock products

MCP parameter:

{
  "database": "my_database",
  "query": "SELECT category, COUNT(*) as count, AVG(price) as avg_price FROM products WHERE in_stock = true GROUP BY category ORDER BY count DESC",
  "maxRows": 100
}

Verificando o Status da Consulta

{
  "queryExecutionId": "12345-67890-abcdef"
}

Obtendo Resultados para uma Consulta Concluída

{
  "queryExecutionId": "12345-67890-abcdef",
  "maxRows": 10
}

Listando Consultas Salvas

{
  "name": "list_saved_queries",
  "arguments": {}
}

Executando uma Consulta Salva

{
  "name": "run_saved_query",
  "arguments": {
    "namedQueryId": "abcd-1234-efgh-5678",
    "maxRows": 100
  }
}

Requisitos

Node.js >= 16
Credenciais AWS com permissões apropriadas de Athena e S3
Bucket S3 para resultados de consultas
Consultas nomeadas (opcionais) devem existir no ATHENA_WORKGROUP e AWS_REGION especificados

Licença

MIT

Repositório

Repositório GitHub