BigQuery

Accede y almacena en caché los metadatos de Google Cloud BigQuery.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de BigQuery

Python Version Framework

Este es un servidor MCP (Protocolo de Contexto de Modelo) basado en Python que recupera información de conjuntos de datos, tablas y esquemas de Google Cloud BigQuery, la almacena en caché localmente y la sirve a través de MCP. Su propósito principal es permitir que los sistemas de IA generativa comprendan rápidamente la estructura de BigQuery y ejecuten consultas de forma segura.

Características principales

  • Gestión de metadatos: Recupera y almacena en caché información sobre conjuntos de datos, tablas y columnas de BigQuery
  • Búsqueda por palabras clave: Admite búsqueda por palabras clave en los metadatos almacenados en caché
  • Ejecución segura de consultas: Proporciona capacidades de ejecución de SQL con inserción automática de la cláusula LIMIT y control de costos
  • Exportación de archivos: Ejecuta consultas y guarda los resultados en archivos locales en formato CSV o JSONL
  • Cumplimiento de MCP: Ofrece herramientas a través del Protocolo de Contexto de Modelo

Herramientas del servidor MCP

Herramientas disponibles:

  1. get_datasets - Recupera una lista de todos los conjuntos de datos
  2. get_tables - Recupera todas las tablas dentro de un conjunto de datos especificado (requiere dataset_id, opcionalmente acepta project_id)
  3. search_metadata - Busca metadatos de conjuntos de datos, tablas y columnas
  4. execute_query - Ejecuta consultas SQL de BigQuery de forma segura con inserción automática de la cláusula LIMIT y control de costos
  5. check_query_scan_amount - Recupera la cantidad de escaneo para consultas SQL de BigQuery
  6. save_query_result - Ejecuta consultas SQL de BigQuery y guarda los resultados en archivos locales (formato CSV o JSONL)

Detalles de las herramientas

save_query_result

La herramienta save_query_result proporciona ejecución avanzada de consultas con capacidades de exportación de archivos:

Parámetros:

  • sql (obligatorio): Consulta SQL a ejecutar
  • output_path (obligatorio): Ruta de archivo local para guardar los resultados
  • format (opcional): Formato de salida - "csv" (predeterminado) o "jsonl"
  • project_id (opcional): ID del proyecto GCP de destino
  • include_header (opcional): Incluir fila de encabezado en la salida CSV (predeterminado: true)

Características principales:

  • Sin LIMIT automático: A diferencia de execute_query, esta herramienta no agrega automáticamente cláusulas LIMIT a sus consultas SQL
  • Control de costos: Mantiene límites de cantidad de escaneo (predeterminado: 1 GB) y verificaciones de seguridad para evitar consultas costosas
  • Seguridad: La validación de rutas previene ataques de recorrido de directorios
  • Formatos flexibles: Admite formatos de salida CSV y JSONL
  • Soporte para conjuntos de datos grandes: Maneja resultados de consultas grandes de manera eficiente dentro de los límites de escaneo

Ejemplo de uso:

-- Export all rows without LIMIT restriction (subject to scan amount limits)
SELECT customer_id, order_date, total_amount 
FROM `project.dataset.orders` 
WHERE order_date >= '2024-01-01'

Nota importante: Aunque esta herramienta no agrega cláusulas LIMIT, igualmente aplica límites de cantidad de escaneo para protección de costos. Las consultas que escaneen más del límite configurado (predeterminado: 1 GB) serán rechazadas.

Instalación y configuración del entorno

Requisitos previos

  • Python 3.11 o posterior
  • Cuenta de Google Cloud Platform
  • Proyecto GCP con la API de BigQuery habilitada

Instalar

uv

uv add bq_mcp_server

pip

pip install bq_mcp_server

Instalación de dependencias

Este proyecto utiliza uv para la gestión de paquetes:

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

Configuración de opciones

Para obtener una lista de los valores de configuración, consulte:

docs/settings.md

Configuración de MCP

Claude Code

claude mcp add bq_mcp_server -- uvx --from git+https://github.com/takada-at/bq_mcp_server bq_mcp_server --project-ids <your project ids>

JSON

{
    "mcpServers": {
        "bq_mcp_server": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/takada-at/bq_mcp_server",
                "bq_mcp_server",
                "--project-ids",
                "<your project ids>"
            ]
        }
    }
}

Ejecución de pruebas

Ejecutar todas las pruebas

pytest

Ejecutar archivos de prueba específicos

pytest tests/test_logic.py

Ejecutar funciones de prueba específicas

pytest -k test_function_name

Verificación de la cobertura de pruebas

pytest --cov=bq_mcp_server

Desarrollo local

Iniciar el servidor MCP

uv run bq_mcp_server

Iniciar el servidor de API REST FastAPI

uvicorn bq_mcp_server.adapters.web:app --reload

Comandos de desarrollo

Formato de código y linting

# Code formatting
ruff format

# Linting checks
ruff check

# Automatic fixes
ruff check --fix

Gestión de dependencias

# Adding new dependencies
uv add <package>

# Adding development dependencies
uv add --dev <package>

# Updating dependencies
uv sync