Servidor MCP de GCP BigQuery

Servidor MCP (Model Context Protocol) de nivel empresarial para Google Cloud Platform BigQuery con autenticación mediante Workload Identity Federation. Proporciona acceso seguro y sin claves a BigQuery a través del Model Context Protocol.

Características principales

• Cero claves de cuenta de servicio - 100% Workload Identity Federation

• Integración con Google Workspace - Autenticación de usuario OIDC

• Compatible con el protocolo MCP - Sigue las mejores prácticas oficiales del SDK de MCP

• Multi-inquilino - Lista de permitidos en YAML + Condiciones de IAM en conjuntos de datos de BigQuery

• Middleware de seguridad - Limitación de tasa, detección de inyección de prompts, redacción de datos

• Pre-verificación Model Armor - Análisis opcional de seguridad de contenido antes de la ejecución de herramientas

• Private Service Connect - Entrada privada opcional para consumidores empresariales

• Cifrado gestionado por el cliente - CMEK para conjuntos de datos de BigQuery

• Registro de auditoría integral - Retención de 7 años para cumplimiento normativo

• Infraestructura con Terraform - IaC completo para despliegues reproducibles

• Despliegue en Cloud Run - Arquitectura sin servidor y de escalado automático

• OpenTelemetry - Trazabilidad distribuida y métricas por inquilino

Related MCP server: bq_mcp_server

Estructura del proyecto

db-mcp/
├── src/                       # TypeScript source code
│   ├── auth/                  # WIF authentication modules
│   ├── bigquery/              # BigQuery client, discovery, optimization
│   ├── mcp/                   # MCP protocol handlers and tools
│   ├── security/              # Security middleware
│   ├── monitoring/            # Health checks and monitoring
│   ├── telemetry/             # OpenTelemetry instrumentation
│   ├── config/                # Configuration management
│   └── utils/                 # Logging utilities
├── tests/                     # Unit, integration, and performance tests
├── terraform/                 # Infrastructure as Code
│   └── modules/               # Reusable Terraform modules
├── docs/                      # Comprehensive documentation
├── scripts/                   # Deployment and utility scripts
├── examples/                  # Usage examples
├── .github/workflows/         # CI/CD automation
└── Dockerfile                 # Production container image

Arquitectura de seguridad

Enfoque tradicional (evitado)

• Claves de cuenta de servicio almacenadas en archivos/secretos

• Credenciales permanentes que nunca caducan

• Rotación manual de claves requerida

• Alto riesgo de filtración de credenciales

Workload Identity Federation (implementado)

• Sin claves en ninguna parte del sistema

• Vida útil del token de 1 hora con rotación automática

• Acceso basado en atributos para un control detallado

• Pista de auditoría completa para todo el acceso

• Reducción del 90% en la superficie de ataque

Inicio rápido

Requisitos previos

• Proyecto de GCP con facturación habilitada

• Terraform >= 1.5.0

• Node.js >= 22.0.0

• Docker (para contenedorización)

Instalación

# Clone and install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Build the project
npm run build

Desarrollo local

# Development mode with hot reload
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

Despliegue en producción

# Build Docker image
docker build -t mcp-bigquery-server .

# Deploy infrastructure with Terraform
cd terraform
terraform init
terraform apply

# Deploy to Cloud Run
gcloud run deploy mcp-bigquery-server \
  --image gcr.io/YOUR_PROJECT/mcp-bigquery-server \
  --region us-central1

Herramientas MCP

El servidor proporciona estas herramientas MCP:

Capacidades del servidor:

• Recursos: Listado de conjuntos de datos de BigQuery

• Herramientas: Ejecución de consultas e inspección de esquemas

• Registro en Stderr: Todos los registros a stderr (compatible con JSON-RPC)

• Apagado elegante: Manejo de SIGTERM/SIGINT

Arquitectura

Client Request
  ↓
MCP Protocol Layer (JSON-RPC)
  ↓
Security Middleware (rate limiting, injection detection)
  ↓
Workload Identity Federation
  ↓ (OIDC Token)
Identity Pool
  ↓ (Attribute Mapping)
Service Account Impersonation
  ↓ (1-hour access token)
BigQuery API

Componentes principales

1. Workload Identity Federation - Grupos de identidad para desarrollo/staging/producción con proveedores OIDC

2. Middleware de seguridad - Limitación de tasa, detección de inyección de prompts, prevención de inyección SQL

3. Integración con BigQuery - Agrupación de conexiones, optimización de consultas, descubrimiento de conjuntos de datos

4. Monitoreo - Verificaciones de estado, trazabilidad con OpenTelemetry, integración con Cloud Monitoring

Documentación

Pruebas

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:performance

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Comandos de desarrollo

npm run build       # Build TypeScript
npm run dev         # Development with hot reload
npm run start       # Start production server
npm run lint        # Run ESLint
npm run lint:fix    # Fix linting issues
npm run format      # Format with Prettier
npm run typecheck   # TypeScript type checking

CI/CD

El flujo de trabajo de GitHub Actions automáticamente:

1. Ejecuta pruebas en solicitudes de extracción (pull requests)

2. Construye y envía la imagen de Docker

3. Despliega en Cloud Run en la rama principal

4. Utiliza Workload Identity Federation (sin claves)

Monitoreo

• Cloud Monitoring: Paneles preconfigurados con dimensión tenant_id en mcp.tool.calls.total y mcp.tool.call.duration

• Cloud Logging: Registros JSON estructurados

• Cloud Trace: Trazabilidad distribuida mediante OpenTelemetry con atributo de span tenant.id

• Registros de auditoría: Retención de 7 años en BigQuery

• Alertas: Notificaciones por correo electrónico/Slack

Cumplimiento

• GDPR: Residencia de datos y registro de acceso

• HIPAA: Controles de acceso y pistas de auditoría

• SOC 2: Gestión de identidad y monitoreo

• PCI-DSS: Autenticación y autorización

Contribución

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para conocer las directrices.

Licencia

Licencia MIT - consulta LICENSE para más detalles

Agradecimientos

• Creado con MCP SDK

• Impulsado por Google Cloud BigQuery

• Infraestructura por Terraform

Estado: Listo para producción Versión: 1.0.0 Última actualización: Abril de 2026