Servidor MCP de BigQuery

Un servidor de Protocolo de Contexto de Modelo (MCP) para acceder a Google BigQuery. Este servidor permite que los Modelos de Lenguaje Grandes (LLM) comprendan las estructuras de los conjuntos de datos de BigQuery y ejecuten consultas SQL.

Características

Autenticación y gestión de conexiones

Admite credenciales predeterminadas de la aplicación (ADC) o archivos de clave de cuenta de servicio
Configuración de ubicación e identificación del proyecto configurables
Verificación de autenticación al iniciar

Herramientas

consulta
- Ejecutar consultas SQL de BigQuery de solo lectura (SELECT)
- Resultados máximos configurables y bytes facturados
- Comprobaciones de seguridad para evitar consultas que no sean SELECT
lista_todos_los_conjuntos_de_datos
- Enumere todos los conjuntos de datos del proyecto
- Devuelve una matriz de identificadores de conjuntos de datos
lista_todas_las_tablas_con_conjunto_de_datos
- Enumere todas las tablas de un conjunto de datos específico con sus esquemas
- Requiere un parámetro datasetId
- Devuelve identificadores de tabla, esquemas, información de partición de tiempo y descripciones
obtener_información_de_tabla
- Obtener el esquema de la tabla y datos de muestra (hasta 20 filas)
- Compatibilidad con tablas particionadas con filtros de partición
- Advertencias para consultas en tablas particionadas sin filtros
consulta de ejecución en seco
- Verificar la validez de la consulta y estimar el coste sin ejecución
- Tamaño del procesamiento de devoluciones y costo estimado

Características de seguridad

Sólo 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 de Docker

También puedes 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 utilizar este servidor con un LLM habilitado para 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 utilizar las credenciales predeterminadas de la aplicación 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 las credenciales predeterminadas de la aplicación

Para autenticarse utilizando las credenciales predeterminadas de la aplicación:

Instale el SDK de Google Cloud si aún no lo ha hecho:
# For macOS brew install --cask google-cloud-sdk # For other platforms, see: https://cloud.google.com/sdk/docs/install
Ejecute el comando de autenticación:
gcloud auth application-default login
Siga las instrucciones para iniciar sesión con su cuenta de Google que tiene acceso al proyecto de BigQuery.
Las credenciales se guardarán en su máquina local y el servidor BigQuery MCP las utilizará automáticamente.

Pruebas

Puede utilizar el inspector para realizar pruebas y depuraciones.

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 puedes 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 Node.js de ejemplo 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 (obligatorio)
--location : ubicación de BigQuery (predeterminada: asia-northeast1)
--key-file : Ruta al archivo de clave de la 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 del usuario deben tener una de las siguientes:

roles/bigquery.user (recomendado)

O ambos:

roles/bigquery.dataViewer (para leer datos de la tabla)
roles/bigquery.jobUser (para ejecutar consultas)

Ejemplo de uso

Herramienta de consulta

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

Herramienta Listar todos los conjuntos de datos

// No parameters required

Listar todas las tablas con la herramienta Conjunto de datos

{
  "datasetId": "your_dataset"
}

Herramienta para obtener información de la tabla

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

Herramienta de consulta de ejecución en seco

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

Manejo de errores

El servidor proporciona mensajes de error detallados para:

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

Estructura del código

El servidor está organizado en 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

Instituto Tecnológico de Massachusetts (MIT)

BigQuery MCP Server

Integrations