mcp-bigquery

Exploración segura de BigQuery a través de Model Context Protocol

Documentación | Inicio rápido | Ejemplos

Resumen

mcp-bigquery es un servidor de Model Context Protocol (MCP) que permite a los asistentes de IA (como Claude) interactuar de forma segura con Google BigQuery.

Características principales

• Ejecución segura: Todas las operaciones están estrictamente limitadas a la verificación de dry-run. El servidor nunca ejecuta consultas que muten datos o incurran en costos de ejecución.

• Transparencia de costos: Proporciona estimaciones de costos de consulta y bytes procesados antes de la ejecución.

• Análisis estático: Analiza las dependencias de las consultas y valida la sintaxis SQL.

• Exploración de esquemas: Navega por conjuntos de datos, tablas y columnas.

Valor para el negocio

Related MCP server: mcp-bigquery-dryrun

Inicio rápido

Paso 1: Instalación

Instale el paquete mediante pip:

pip install mcp-bigquery

Paso 2: Autenticación

Configure la autenticación de Google Cloud Platform:

# For user account authentication
gcloud auth application-default login

# For service account authentication
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Paso 3: Configuración de Claude Desktop

Configure el servidor en el archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Añada la siguiente entrada:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "your-gcp-project-id"
      }
    }
  }
}

Paso 4: Verificación

Reinicie Claude Desktop y ejecute las siguientes consultas para verificar la configuración:

• "¿Qué conjuntos de datos están disponibles en mi proyecto de BigQuery?"

• "¿Puedes estimar el costo de: SELECT * FROM dataset.table"

• "Muéstrame el esquema de la tabla users"

Herramientas disponibles

Validación y análisis de SQL

Descubrimiento de esquemas

[!IMPORTANTE] La herramienta bq_preview_table utiliza client.list_rows (API: tabledata.list) para recuperar filas de muestra directamente, lo que resulta en cero bytes escaneados y sin costos de ejecución. Para evitar la exposición no intencional de información sensible (como PII) al LLM, esta herramienta está deshabilitada por defecto. Debe optar explícitamente configurando MCP_BQ_ENABLE_PREVIEW=true en su configuración de entorno.

Configuración

Variables de entorno

Ejemplo de archivo .env

Para entornos de prueba locales o de desarrollo, puede definir estas variables en un archivo .env:

BQ_PROJECT=your-gcp-project-id
BQ_LOCATION=asia-northeast1
SAFE_PRICE_PER_TIB=5.0
LOG_LEVEL=WARNING
MCP_BQ_ENABLE_PREVIEW=true

Ejemplo completo de configuración de Claude Desktop

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "my-production-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "6.0",
        "LOG_LEVEL": "WARNING",
        "MCP_BQ_ENABLE_PREVIEW": "true"
      }
    }
  }
}

Solución de problemas

Errores mapeados y soluciones

Error de autenticación

Error: Could not automatically determine credentials

• Solución: Vuelva a autenticarse usando la línea de comandos:

  gcloud auth application-default login

Permiso denegado

Error: User does not have bigquery.tables.get permission

• Solución: Otorgue el rol BigQuery Data Viewer a la identidad objetivo:

  gcloud projects add-iam-policy-binding YOUR_PROJECT \
    --member="user:your-email@example.com" \
    --role="roles/bigquery.dataViewer"

Falta el ID del proyecto

Error: Project ID is required

• Solución: Asegúrese de que la variable BQ_PROJECT esté configurada correctamente en su configuración.

Ejemplos de uso

Ejemplo 1: Verificar costos antes de ejecutar

# Before running an expensive query...
query = "SELECT * FROM `bigquery-public-data.github_repos.commits`"

# First, check the cost
result = bq_dry_run_sql(sql=query)
print(f"Estimated cost: ${result['usdEstimate']}")
print(f"Data processed: {result['totalBytesProcessed'] / 1e9:.2f} GB")

# Output:
# Estimated cost: $12.50
# Data processed: 2500.00 GB

Ejemplo 2: Comprender la estructura de la tabla

# Check table schema
result = bq_describe_table(
    dataset_id="your_dataset",
    table_id="users"
)

# Output:
# ├── user_id (INTEGER, REQUIRED)
# ├── email (STRING, NULLABLE)
# ├── created_at (TIMESTAMP, REQUIRED)
# └── profile (RECORD, REPEATED)
#     ├── name (STRING)
#     └── age (INTEGER)

Ejemplo 3: Rastrear dependencias de datos

# Understand query dependencies
query = """
WITH user_stats AS (
  SELECT user_id, COUNT(*) as order_count
  FROM orders
  GROUP BY user_id
)
SELECT u.name, s.order_count
FROM users u
JOIN user_stats s ON u.id = s.user_id
"""

result = bq_extract_dependencies(sql=query)

# Output:
# Tables: ['orders', 'users']
# Columns: ['user_id', 'name', 'id']
# Dependency Graph:
#   orders → user_stats → final_result
#   users → final_result

Estado del proyecto e historial de versiones

Desarrollo y contribución

Para obtener instrucciones sobre la configuración de desarrollo local y las políticas de contribución, consulte la guía CONTRIBUTING.md.

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

# Install development dependencies
pip install -e ".[dev]"

# Execute the test suite
pytest tests/

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte LICENSE para obtener más detalles.