BigQuery

Accede a Google BigQuery para entender las estructuras de conjuntos de datos y ejecutar consultas SQL.

GitHub
5

Documentación

BigQuery MCP Server

Un servidor de Model Context Protocol (MCP) para acceder a Google BigQuery. Este servidor permite que los Modelos de Lenguaje de Gran Tamaño (LLMs) comprendan las estructuras de datasets de BigQuery y ejecuten consultas SQL.

Características

Gestión de autenticación y conexión

  • Soporta Application Default Credentials (ADC) o archivos de clave de cuenta de servicio
  • Configuración de ID de proyecto y ubicación configurables
  • Verificación de autenticación al inicio

Herramientas

  1. query

    • Ejecutar consultas SQL de BigQuery de solo lectura (SELECT)
    • Máximo de resultados y bytes facturados configurables
    • Comprobaciones de seguridad para evitar consultas que no sean SELECT

  2. list_all_datasets

    • Listar todos los datasets del proyecto
    • Devuelve un array de IDs de datasets

  3. list_all_tables_with_dataset

    • Listar todas las tablas de un dataset específico con sus esquemas
    • Requiere un parámetro datasetId
    • Devuelve IDs de tablas, esquemas, información de particionado por tiempo y descripciones

  4. get_table_information

    • Obtener el esquema de la tabla y datos de muestra (hasta 20 filas)
    • Soporte para tablas particionadas con filtros de partición
    • Advertencias para consultas en tablas particionadas sin filtros

  5. dry_run_query

    • Verificar la validez de la consulta y estimar el costo sin ejecución
    • Devuelve el tamaño de procesamiento y el costo estimado

Características de seguridad

  • Solo se permiten consultas SELECT (acceso de solo lectura)
  • Límite predeterminado de 500 GB para el procesamiento de consultas para evitar costos excesivos
  • Recomendaciones de filtros de partición para tablas particionadas
  • Manejo seguro de credenciales de autenticación

Instalación

Instalación 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

Instalación con Docker

También puede ejecutar el servidor en un contenedor 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

O usando Docker Compose:

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

Configuración de MCP

Para usar este servidor con un LLM compatible con MCP, agréguelo a su configuración de 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"
      }
    }
  }
}

También puede usar Application Default Credentials en lugar de un archivo de clave de cuenta de servicio:

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

Configuración de Application Default Credentials

Para autenticarse con Application Default Credentials:

  1. Instale el SDK de Google Cloud si aún no lo tiene:

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

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

  2. Ejecute el comando de autenticación:

    gcloud auth application-default login

  3. Siga las instrucciones para iniciar sesión con su cuenta de Google que tenga acceso al proyecto de BigQuery.

  4. Las credenciales se guardarán en su máquina local y el servidor de BigQuery MCP las utilizará automáticamente.

Pruebas

Puede usar inspector para realizar pruebas y depuración.

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

Uso

Uso del script auxiliar

El script run-server.sh incluido facilita el inicio del servidor con configuraciones comunes:

# 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

Ejecución manual

También puede ejecutar el binario compilado directamente:

# 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

Cliente de ejemplo

Se incluye un cliente de ejemplo en Node.js en el directorio 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

Opciones de línea de comandos

  • --project-id: ID del proyecto de Google Cloud (requerido)
  • --location: Ubicación de BigQuery (predeterminado: asia-northeast1)
  • --key-file: Ruta al archivo de clave de cuenta de servicio (opcional)
  • --max-results: Máximo de filas a devolver (predeterminado: 1000)
  • --max-bytes-billed: Máximo de bytes a procesar (predeterminado: 500000000000, 500 GB)

Permisos requeridos

La cuenta de servicio o las credenciales de usuario deben tener uno de los siguientes:

  • roles/bigquery.user (recomendado)

O ambos de los siguientes:

  • roles/bigquery.dataViewer (para leer datos de tablas)
  • roles/bigquery.jobUser (para ejecutar consultas)

Ejemplo de uso

Herramienta de consulta

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

Herramienta de listado de datasets

// No parameters required

Herramienta de listado de tablas con dataset

{
  "datasetId": "your_dataset"
}

Herramienta de información de tabla

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

Herramienta de ejecución en seco de consultas

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

Manejo de errores

El servidor proporciona mensajes de error detallados para:

  • Fallos de autenticación
  • Problemas de permisos
  • Consultas no válidas
  • Filtros de partición faltantes
  • Solicitudes de procesamiento de datos excesivas

Estructura del código

El servidor está organizado con la siguiente estructura:

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

Licencia

MIT