GCP BigQuery MCP Server

MCP-сервер (Model Context Protocol) корпоративного уровня для Google Cloud Platform BigQuery с аутентификацией Workload Identity Federation. Обеспечивает безопасный доступ к BigQuery без использования ключей через протокол Model Context Protocol.

Основные возможности

• Без ключей сервисных аккаунтов — 100% Workload Identity Federation

• Интеграция с Google Workspace — OIDC-аутентификация пользователей

• Соответствие протоколу MCP — соблюдение лучших практик официального SDK MCP

• Мультитенантность — YAML-списки разрешений + IAM Conditions для наборов данных BigQuery

• Middleware безопасности — ограничение частоты запросов (rate limiting), обнаружение инъекций промптов, маскирование данных

• Предварительная проверка Model Armor — опциональная проверка безопасности контента перед выполнением инструментов

• Private Service Connect — опциональный частный вход для корпоративных потребителей

• Шифрование, управляемое клиентом — CMEK для наборов данных BigQuery

• Комплексное логирование аудита — хранение в течение 7 лет для соответствия требованиям

• Инфраструктура Terraform — полная IaC для воспроизводимых развертываний

• Развертывание в Cloud Run — бессерверная архитектура с автоматическим масштабированием

• OpenTelemetry — распределенная трассировка и метрики для каждого тенанта

Related MCP server: bq_mcp_server

Структура проекта

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

Архитектура безопасности

Традиционный подход (избегается)

• Ключи сервисных аккаунтов хранятся в файлах/секретах

• Постоянные учетные данные, которые никогда не истекают

• Требуется ручная ротация ключей

• Высокий риск утечки учетных данных

Workload Identity Federation (реализовано)

• Никаких ключей в системе

• Время жизни токена 1 час с автоматической ротацией

• Доступ на основе атрибутов для детального контроля

• Полный след аудита для всех обращений

• Снижение поверхности атаки на 90%

Быстрый старт

Предварительные требования

• Проект GCP с включенным биллингом

• Terraform >= 1.5.0

• Node.js >= 22.0.0

• Docker (для контейнеризации)

Установка

# Clone and install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Build the project
npm run build

Локальная разработка

# Development mode with hot reload
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

Развертывание в продакшн

# 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

Инструменты MCP

Сервер предоставляет следующие инструменты MCP:

Возможности сервера:

• Ресурсы: список наборов данных BigQuery

• Инструменты: выполнение запросов и проверка схем

• Логирование в Stderr: все логи выводятся в stderr (совместимо с JSON-RPC)

• Корректное завершение работы: обработка сигналов SIGTERM/SIGINT

Архитектура

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

Основные компоненты

1. Workload Identity Federation — пулы идентификации для dev/staging/prod с OIDC-провайдерами

2. Middleware безопасности — ограничение частоты запросов, обнаружение инъекций промптов, предотвращение SQL-инъекций

3. Интеграция с BigQuery — пулинг соединений, оптимизация запросов, обнаружение наборов данных

4. Мониторинг — проверки работоспособности, трассировка OpenTelemetry, интеграция с Cloud Monitoring

Документация

Тестирование

# 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

Команды разработки

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

Рабочий процесс GitHub Actions автоматически:

1. Запускает тесты при создании pull request

2. Собирает и отправляет Docker-образ

3. Развертывает в Cloud Run при обновлении основной ветки

4. Использует Workload Identity Federation (без ключей)

Мониторинг

• Cloud Monitoring: Предварительно настроенные дашборды с измерением tenant_id для mcp.tool.calls.total и mcp.tool.call.duration

• Cloud Logging: Структурированные JSON-логи

• Cloud Trace: Распределенная трассировка через OpenTelemetry с атрибутом спана tenant.id

• Логи аудита: Хранение в течение 7 лет в BigQuery

• Оповещения: Уведомления по Email/Slack

Соответствие требованиям

• GDPR: Локализация данных и логирование доступа

• HIPAA: Контроль доступа и следы аудита

• SOC 2: Управление идентификацией и мониторинг

• PCI-DSS: Аутентификация и авторизация

Вклад в проект

Приветствуем участие в разработке! См. CONTRIBUTING.md для ознакомления с правилами.

Лицензия

Лицензия MIT — подробности см. в LICENSE

Благодарности

• Создано с помощью MCP SDK

• Работает на базе Google Cloud BigQuery

• Инфраструктура от Terraform

Статус: Готово к продакшну Версия: 1.0.0 Последнее обновление: Апрель 2026