BigQuery

Acesse o Google BigQuery para entender estruturas de conjuntos de dados e executar consultas SQL.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Servidor MCP BigQuery

Um servidor Model Context Protocol (MCP) para acessar o Google BigQuery. Este servidor permite que Modelos de Linguagem de Grande Porte (LLMs) entendam as estruturas de datasets do BigQuery e executem consultas SQL.

Recursos

Gerenciamento de Autenticação e Conexão

  • Suporte a Application Default Credentials (ADC) ou arquivos de chave de conta de serviço
  • Configuração de ID do projeto e localização
  • Verificação de autenticação na inicialização

Ferramentas

  1. query

    • Executar consultas SQL do BigQuery somente leitura (SELECT)
    • Resultados máximos e bytes cobrados configuráveis
    • Verificações de segurança para impedir consultas que não sejam SELECT

  2. list_all_datasets

    • Listar todos os datasets no projeto
    • Retorna uma matriz de IDs de datasets

  3. list_all_tables_with_dataset

    • Listar todas as tabelas em um dataset específico com seus esquemas
    • Requer um parâmetro datasetId
    • Retorna IDs das tabelas, esquemas, informações de particionamento por tempo e descrições

  4. get_table_information

    • Obter esquema da tabela e dados de amostra (até 20 linhas)
    • Suporte para tabelas particionadas com filtros de partição
    • Avisos para consultas em tabelas particionadas sem filtros

  5. dry_run_query

    • Verificar a validade da consulta e estimar o custo sem executá-la
    • Retorna o tamanho do processamento e o custo estimado

Recursos de Segurança

  • Apenas consultas SELECT são permitidas (acesso somente leitura)
  • Limite padrão de 500GB para processamento de consultas, a fim de evitar custos excessivos
  • Recomendações de filtro de partição para tabelas particionadas
  • Tratamento seguro das credenciais de autenticação

Instalação

Instalação Local

# Clone the repository
git clone https://github.com/yourusername/bigquery-mcp-server.git
cd bigquery-mcp-server

# Install dependencies
bun install

# Build the server
bun run build

# Install command to your own path.
cp dist/bigquery-mcp-server /path/to/your_place

Instalação via Docker

Você também pode executar o servidor em um contêiner Docker:

# Build the Docker image
docker build -t bigquery-mcp-server .

# Run the container
docker run -it --rm \
  bigquery-mcp-server \
  --project-id=your-project-id

Ou usando Docker Compose:

# Edit docker-compose.yml to set your project ID and other options
# Then run:
docker-compose up

Configuração MCP

Para usar este servidor com um LLM habilitado para MCP, adicione-o à sua configuração MCP:

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",
        "your-project-id",
        "--location",
        "asia-northeast1",
        "--max-results",
        "1000",
        "--max-bytes-billed",
        "500000000000"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
      }
    }
  }
}

Você também pode usar Application Default Credentials em vez de um arquivo de chave de conta de serviço:

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",
        "your-project-id",
        "--location",
        "asia-northeast1",
        "--max-results",
        "1000",
        "--max-bytes-billed",
        "500000000000"
      ]
    }
  }
}

Configurando Application Default Credentials

Para autenticar usando Application Default Credentials:

  1. Instale o Google Cloud SDK se ainda não o fez:

    # For macOS
brew install --cask google-cloud-sdk

# For other platforms, see: https://cloud.google.com/sdk/docs/install

  2. Execute o comando de autenticação:

    gcloud auth application-default login

  3. Siga as instruções para entrar com sua conta Google que tenha acesso ao projeto BigQuery.

  4. As credenciais serão salvas na sua máquina local e usadas automaticamente pelo servidor MCP BigQuery.

Testes

Você pode usar o inspector para testes e depuração.

npx @modelcontextprotocol/inspector dist/bigquery-mcp-server --project-id={{your_own_project}}

Uso

Usando o Script Auxiliar

O script run-server.sh incluído facilita a inicialização do servidor com configurações comuns:

# Make the script executable
chmod +x run-server.sh

# Run with Application Default Credentials
./run-server.sh --project-id=your-project-id

# Run with a service account key file
./run-server.sh \
  --project-id=your-project-id \
  --location=asia-northeast1 \
  --key-file=/path/to/service-account-key.json \
  --max-results=1000 \
  --max-bytes-billed=500000000000

Execução Manual

Você também pode executar o binário compilado diretamente:

# Run with Application Default Credentials
./dist/bigquery-mcp-server --project-id=your-project-id

# Run with a service account key file
./dist/bigquery-mcp-server \
  --project-id=your-project-id \
  --location=asia-northeast1 \
  --key-file=/path/to/service-account-key.json \
  --max-results=1000 \
  --max-bytes-billed=500000000000

Exemplo de Cliente

Um cliente Node.js de exemplo está incluído no diretório examples:

# Make the example executable
chmod +x examples/sample-query.js

# Edit the example to set your project ID
# Then run it
cd examples
./sample-query.js

Opções de Linha de Comando

  • --project-id: ID do projeto Google Cloud (obrigatório)
  • --location: Localização do BigQuery (padrão: asia-northeast1)
  • --key-file: Caminho para o arquivo de chave da conta de serviço (opcional)
  • --max-results: Número máximo de linhas a retornar (padrão: 1000)
  • --max-bytes-billed: Máximo de bytes a processar (padrão: 500000000000, 500GB)

Permissões Necessárias

A conta de serviço ou as credenciais do usuário devem ter uma das seguintes permissões:

  • roles/bigquery.user (recomendado)

Ou ambas:

  • roles/bigquery.dataViewer (para ler dados de tabelas)
  • roles/bigquery.jobUser (para executar consultas)

Exemplo de Uso

Ferramenta de Consulta

{
  "query": "SELECT * FROM `project.dataset.table` LIMIT 10",
  "maxResults": 100
}

Ferramenta de Listagem de Todos os Datasets

// No parameters required

Ferramenta de Listagem de Todas as Tabelas com Dataset

{
  "datasetId": "your_dataset"
}

Ferramenta de Obtenção de Informações da Tabela

{
  "datasetId": "your_dataset",
  "tableId": "your_table",
  "partition": "20250101"
}

Ferramenta de Dry Run de Consulta

{
  "query": "SELECT * FROM `project.dataset.table` WHERE date = '2025-01-01'"
}

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para:

  • Falhas de autenticação
  • Problemas de permissão
  • Consultas inválidas
  • Filtros de partição ausentes
  • Solicitações de processamento excessivo de dados

Estrutura do Código

O servidor está organizado na seguinte estrutura:

src/
├── index.ts              # Entry point
├── server.ts             # BigQueryMcpServer class
├── types.ts              # Type definitions
├── tools/                # Tool implementations
│   ├── query.ts          # query tool
│   ├── list-datasets.ts  # list_all_datasets tool
│   ├── list-tables.ts    # list_all_tables_with_dataset tool
│   ├── table-info.ts     # get_table_information tool
│   └── dry-run.ts        # dry_run_query tool
└── utils/                # Utility functions
    ├── args-parser.ts    # Command line argument parser
    └── query-utils.ts    # Query validation and response formatting

Licença

MIT