BigQuery

Servidor MCP de BigQuery

¿Qué es esto? 🤔

Este es un servidor que permite que tus LLMs (como Claude) hablen directamente con tus datos de BigQuery — de solo lectura, sin capacidad de modificar tu almacén de datos. Piénsalo como un traductor amigable que se sitúa entre tu asistente de IA y tu base de datos, asegurando que puedan conversar de forma segura y eficiente.

Ejemplo rápido

You: "What were our top 10 customers last month?"
Claude: *queries your BigQuery database and gives you the answer in plain English*

¡No más escribir consultas SQL a mano — simplemente conversa naturalmente con tus datos!

¿Cómo funciona? 🛠️

Este servidor utiliza el Protocolo de Contexto de Modelo (MCP), que es como un traductor universal para la comunicación entre IA y bases de datos. MCP es compatible con Claude Desktop, Claude Code y un número creciente de otros clientes de IA.

Esto es todo lo que necesitas hacer:

1. Configura la autenticación (ver más abajo)
2. Añade los detalles de tu proyecto al archivo de configuración de tu cliente MCP
3. ¡Empieza a conversar naturalmente con tus datos de BigQuery!

¿Qué puede hacer? 📊

• Solo lectura por diseño — solo se permiten sentencias SELECT. Cada consulta es validada por el planificador de ejecución en seco de BigQuery antes de ejecutarse, por lo que INSERT, UPDATE, DELETE, DROP, TRUNCATE, EXPORT DATA y MERGE son rechazadas. El agente de IA no puede modificar tu almacén de datos, punto.
• Ejecuta consultas SQL simplemente haciendo preguntas en inglés sencillo
• Accede tanto a tablas como a vistas materializadas en tus conjuntos de datos
• Explora los esquemas de los conjuntos de datos con un etiquetado claro de los tipos de recursos (tablas vs. vistas)
• Analiza datos dentro de límites seguros configurables (establecidos mediante config.json o --maximum-bytes-billed)
• Protege datos sensibles — define restricciones de acceso a nivel de campo para evitar que los agentes de IA lean IPD, IPH, datos financieros y secretos. El agente recibe una guía clara sobre cómo reformular consultas usando agregados o cláusulas EXCEPT, de modo que siga siendo útil sin exponer registros individuales.
• Auto-descubrimiento de campos sensibles — escanea automáticamente todo tu almacén de datos de BigQuery en busca de columnas que coincidan con patrones sensibles (nombres, correos electrónicos, números de seguro social, registros médicos, claves API, etc.) y las añade a la lista restringida. Las nuevas tablas y columnas se protegen automáticamente en cada escaneo — sin necesidad de mantenimiento manual.
• Totalmente configurable — todo se controla mediante config.json. Añade tus propios patrones de detección para que coincidan con las convenciones de nomenclatura de tu organización (por ejemplo, %guardian_name%, %beneficiary%), ajusta la frecuencia de escaneo, establece límites de facturación y define restricciones de campo por tabla. El escáner recoge tus patrones personalizados en la siguiente ejecución y protege automáticamente cualquier columna coincidente en todos los conjuntos de datos.

¿Qué configuración es la adecuada para ti?

	Modo Simple	Modo Protegido
Úsalo cuando	Proyectos personales, datos no sensibles	IPH, IPD, datos financieros, entornos regulados por HIPAA
Instalación	npx — sin configuración local necesaria	npx o compilación local con un config.json
Restricciones de campo	Ninguna	Define preventedFields para bloquear columnas sensibles
Auto-escáner	No disponible	Descubre columnas sensibles en todos los conjuntos de datos automáticamente
Configuración	Configuración rápida abajo	Configuración del modo protegido abajo

Por qué la implementación local es importante para datos sensibles: La inferencia de LLM ocurre en la nube. Cuando un agente de IA consulta BigQuery, los resultados se envían a los servidores del proveedor de LLM (Anthropic, OpenAI, etc.) para su procesamiento — salen de tu red. El IAM de BigQuery controla quién puede alcanzar tus datos; las restricciones de campo controlan lo que el agente de IA expone en las respuestas del LLM. Son límites de protección diferentes. Configurar preventedFields garantiza que la IPH y la IPD nunca entren en el contexto de conversación del LLM, independientemente de cuántas consultas ejecute el agente de forma autónoma.

Inicio rápido 🚀

Requisitos previos

• Node.js 14 o superior
• Proyecto de Google Cloud con BigQuery habilitado
• Google Cloud CLI instalado o un archivo de clave de cuenta de servicio
• Cualquier cliente compatible con MCP (Claude Desktop, Claude Code, etc.)

Configuración rápida

1. Autentícate con Google Cloud:

   gcloud auth application-default login
   

2. Añádelo a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json para Claude Desktop, .mcp.json para Claude Code):

   {
     "mcpServers": {
       "bigquery": {
         "command": "npx",
         "args": [
           "-y",
           "@ergut/mcp-bigquery-server",
           "--project-id",
           "your-project-id"
         ]
       }
     }
   }
   

3. ¡Empieza a conversar! Abre tu cliente MCP y haz preguntas sobre tus datos.

Configuración del modo protegido

Para datos sensibles con restricciones a nivel de campo:

1. Autentícate con Google Cloud (elige un método):

   • Usando Google Cloud CLI (ideal para desarrollo):

     gcloud auth application-default login
     

   • Usando una cuenta de servicio (recomendado para producción):

     # Save your service account key file and use --key-file parameter
     # Remember to keep your service account key file secure and never commit it to version control
     

2. Añádelo a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json para Claude Desktop, .mcp.json para Claude Code):

   • Con credenciales predeterminadas de la aplicación:

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--config-file",
             "/path/to/config.json"
           ]
         }
       }
     }
     

   • Con un archivo de clave de cuenta de servicio:

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--key-file",
             "/path/to/service-account-key.json",
             "--config-file",
             "/path/to/config.json"
           ]
         }
       }
     }
     

3. ¡Empieza a conversar! Abre tu cliente MCP y comienza a hacer preguntas sobre tus datos.

Configuración

El servidor admite un archivo config.json opcional para configuración avanzada. Sin un archivo de configuración (es decir, sin la bandera --config-file), el servidor se ejecuta en Modo Simple con valores predeterminados seguros (límite de consulta de 1 GB, sin restricciones de campo). Para habilitar la protección, pasa --config-file /path/to/config.json al iniciar el servidor.

Estructura de config.json

{
  "maximumBytesBilled": "1000000000",
  "preventedFields": {
    "healthcare.patients": ["first_name", "last_name", "ssn", "date_of_birth", "email"],
    "billing.transactions": ["credit_card_number", "bank_account"]
  },
  "sensitiveFieldPatterns": [
    "%first_name%", "%last_name%", "%email%",
    "%ssn%", "%date_of_birth%", "%password%"
  ],
  "sensitiveFieldScanFrequencyDays": 1
}

Configuración	Predeterminado	Descripción
maximumBytesBilled	"1000000000" (1 GB)	Máximo de bytes facturados por consulta
preventedFields	{}	Mapeo de tabla a columnas de campos restringidos
sensitiveFieldPatterns	Conjunto integrado	Patrones SQL LIKE para auto-descubrimiento
sensitiveFieldScanFrequencyDays	1	Días entre auto-escaneos (0 para deshabilitar)

Argumentos de línea de comandos

• --project-id: (Obligatorio) El ID de tu proyecto de Google Cloud
• --location: (Opcional) Ubicación de BigQuery, el valor predeterminado es 'US'
• --key-file: (Opcional) Ruta al archivo JSON de clave de cuenta de servicio
• --config-file: (Opcional) Ruta a un archivo de configuración. Si se omite, el servidor se ejecuta en Modo Simple sin protección — no hay un valor predeterminado implícito de ./config.json
• --maximum-bytes-billed: (Opcional) Anula el máximo de bytes facturados para consultas, reemplaza el valor de config.json

Ejemplo usando cuenta de servicio:

npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json --config-file /path/to/config.json --maximum-bytes-billed 2000000000

Protección de datos sensibles 🔒

Los almacenes de datos a menudo contienen información altamente sensible — registros de pacientes, números de seguro social, datos financieros, datos de contacto personales y secretos de autenticación. Cuando un agente de IA tiene acceso directo para consultar tu almacén, no hay un humano en el circuito que le impida leer columnas sensibles. Una SELECT * FROM patients podría exponer miles de registros de IPD/IPH, y los resultados se envían luego al proveedor de LLM para su procesamiento — salen de tu red.

Este servidor brinda a los administradores un control granular sobre qué columnas puede acceder un agente de IA. Tú defines preventedFields en config.json y el servidor bloquea las consultas que expondrían esas columnas en las respuestas del LLM. Un escáner automatizado descubre columnas sensibles en todos tus conjuntos de datos, de modo que la cobertura se mantiene actualizada a medida que tu almacén crece.

Advertencia honesta: Las restricciones de campo son salvaguardas cooperativas para agentes de IA — no un firewall SQL estricto contra atacantes adversarios. Consulta PROTECTION.md para conocer el modelo de amenazas completo.

El servidor admite tres modos de protección, establecidos mediante protectionMode en config.json:

Modo	Descripción
off	Sin protección — todas las tablas y campos accesibles (predeterminado cuando no se proporciona un archivo de configuración)
allowedTables	Lista de permitidos de tablas — solo se pueden consultar las tablas enumeradas, con restricciones de campo opcionales dentro de ellas
autoProtect	Escanea automáticamente tus conjuntos de datos en busca de columnas sensibles y aplica preventedFields

Consulta PROTECTION.md para la configuración completa, ejemplos, la referencia de patrones de consulta, la configuración del escáner y los permisos de IAM requeridos.

Compilación local (opcional) 🔧

Ejecuta una compilación local en lugar de npx — útil para contribuir, probar cambios o ejecutar una versión fija. Admite tanto el Modo Simple como el Modo Protegido.

# Clone and install
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm install

# Build
npm run build

Luego apunta la configuración de tu cliente MCP a la compilación local:

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "/path/to/your/clone/mcp-bigquery-server/dist/index.js",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1"
      ]
    }
  }
}

Para el Modo Protegido, añade "--config-file", "/path/to/config.json" al arreglo args (y opcionalmente "--key-file", "/path/to/service-account-key.json" para autenticación con cuenta de servicio).

Limitaciones actuales ⚠️

• Los ejemplos de configuración JSON siguen el formato estándar del servidor MCP. Cualquier cliente compatible con MCP (Claude Desktop, Claude Code, etc.) puede usarlo — consulta la documentación de tu cliente para conocer la ubicación exacta del archivo de configuración
• Los límites de procesamiento son configurables por consulta (establecidos en config.json o mediante --maximum-bytes-billed)
• Si bien se admiten tanto tablas como vistas, algunos tipos de vistas complejas podrían tener limitaciones
• Un archivo config.json es opcional; sin él, el servidor usa valores predeterminados seguros

Soporte y recursos 💬

• 🐛 Reportar problemas
• 💡 Solicitudes de funciones
• 📖 Documentación

Licencia 📝

Licencia MIT — Consulta el archivo LICENSE para más detalles.

Autor ✍️

Salih Ergüt

Patrocinio

Este proyecto está orgullosamente patrocinado por:

Historial de versiones 📋

Consulta CHANGELOG.md para ver actualizaciones e historial de versiones.