GCP BigQuery MCP Server

Enterprise-grade MCP (Model Context Protocol) server for Google Cloud Platform BigQuery with Workload Identity Federation authentication. Provides secure, keyless access to BigQuery through the Model Context Protocol.

Key Features

• Zero Service Account Keys - 100% Workload Identity Federation

• Google Workspace Integration - OIDC user authentication

• MCP Protocol Compliant - Built on the official MCP SDK's StreamableHTTPServerTransport (stateless), 2025-11-25 spec

• Gemini Enterprise Ready - OAuth 2.0 discovery (RFC 8414/9728), stateless Streamable HTTP transport

• Resource Templates + Completions - RFC 6570 URI templates for dataset/table/schema/sample/job/INFORMATION_SCHEMA, with completion/complete autocompletion of dataset/table IDs

• Cost Elicitation Gate - Per-query dry-run guardrail that surfaces high-cost confirmations to clients

• Multi-tenant - YAML allowlist + IAM Conditions on BigQuery datasets

• Security Middleware - Rate limiting, prompt injection detection, data redaction

• Model Armor Pre-flight - Optional content-safety screening before tool execution

• Private Service Connect - Optional private ingress for enterprise consumers

• Customer-Managed Encryption - CMEK for BigQuery datasets

• Comprehensive Audit Logging - 2555-day (7-year) retention via Cloud Logging log bucket with linked BigQuery dataset for compliance

• Terraform Infrastructure - Complete IaC for reproducible deployments

• Cloud Run Deployment - Serverless, auto-scaling architecture

• OpenTelemetry - Distributed tracing and per-tenant metrics

Related MCP server: bq_mcp_server

Project Structure

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/            # Readiness probes and metrics
│   ├── telemetry/             # OpenTelemetry instrumentation
│   ├── config/                # Configuration management
│   └── utils/                 # Logging utilities
├── tests/                     # Unit, integration, and performance tests
├── terraform/                 # Infrastructure as Code
│   └── modules/               # Reusable Terraform modules
├── docs/                      # Documentation (Diátaxis: tutorials/how-to/reference/explanation)
├── scripts/                   # Deployment and utility scripts
├── examples/                  # Usage examples
├── .github/workflows/         # CI/CD automation
└── Dockerfile                 # Production container image

Security Architecture

Traditional Approach (Avoided)

• Service account keys stored in files/secrets

• Permanent credentials that never expire

• Manual key rotation required

• High risk of credential leakage

Workload Identity Federation (Implemented)

• No keys anywhere in the system

• 1-hour token lifetime with automatic rotation

• Attribute-based access for fine-grained control

• Complete audit trail for all access

• 90% reduction in attack surface

Quick Start

First time here? Tutorial 1 walks you from a fresh clone to a working MCP conversation in about ten minutes, and needs no Google Cloud account.

Prerequisites

• Node.js >= 22.0.0 — required for everything below

• GCP Project with billing enabled — only for querying real data

• Terraform >= 1.5.0 — only for deployment

• Docker — only for containerization

Installation

# Clone and install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Build the project
npm run build

GCP_PROJECT_ID is the one required setting; the server exits with Invalid environment configuration without it. See environment variables for the rest.

Local Development

# Development mode with hot reload
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

Production Deployment

All production infrastructure — including the Cloud Run service — is managed by Terraform. Container images are stored in Artifact Registry (europe-west2-docker.pkg.dev). Direct gcloud run deploy commands are not used in production.

# Build and push container image to Artifact Registry
docker build -t europe-west2-docker.pkg.dev/YOUR_PROJECT/db-mcp/mcp-bigquery-server:latest .
docker push europe-west2-docker.pkg.dev/YOUR_PROJECT/db-mcp/mcp-bigquery-server:latest

# Deploy infrastructure with Terraform (provisions Cloud Run + all supporting resources)
cd terraform
terraform init
terraform apply

MCP Tools

The server provides these MCP tools:

Tool annotations are tenant-aware: readOnlyHint is false and destructiveHint true for the SQL-executing tools when the tenant's write mode permits writes, since clients use readOnlyHint to auto-approve calls without prompting.

Server Capabilities:

• Resources: bigquery:// URIs for datasets, tables, schemas, samples, jobs, and INFORMATION_SCHEMA

• Tools: Query execution and schema inspection, with a union output schema covering executed, dry-run, and cost-confirmation responses

• Prompts: 5 BigQuery-specific templates

• Logging: logging/setLevel plus notifications/message for security refusals

• Progress: notifications/progress when the client supplies a _meta.progressToken

• Stderr Logging: All logs to stderr (JSON-RPC compatible)

• Graceful Shutdown: SIGTERM/SIGINT handling

Architecture

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

Core Components

1. Workload Identity Federation - Identity pools for dev/staging/prod with OIDC providers

2. Security Middleware - Rate limiting, prompt injection detection, SQL injection prevention

3. BigQuery Integration - Connection pooling, query optimization, dataset discovery

4. Monitoring - Liveness/readiness probes, Prometheus /metrics, OpenTelemetry tracing, Cloud Monitoring

Documentation

Documentation is organised with Diátaxis — start with the documentation index, or go straight to the section that matches what you are doing:

Most-used pages:

Testing

# Run all tests — 69 suites, 891 tests, none skipped
npm test

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

# Performance suites, with timing budgets enforced
npm run test:performance

# Run with coverage (jest.config.mjs enforces coverageThreshold floors)
npm run test:coverage

# Watch mode
npm run test:watch

Timing-sensitive assertions are gated behind PERF_TIMING_ASSERTIONS=true, set only by npm run test:performance, so ordinary runs measure timing budgets without enforcing them. See how to run the test suite for the coverage floors.

Development Commands

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 workflow automatically:

1. Runs tests on pull requests

2. Builds and pushes Docker image

3. Deploys to Cloud Run on main branch

4. Uses Workload Identity Federation (no keys)

Monitoring

• Cloud Monitoring: Pre-configured dashboards with tenant_id dimension on mcp.tool.calls.total and mcp.tool.call.duration

• Cloud Logging: Structured JSON logs

• Cloud Trace: Distributed tracing via OpenTelemetry with tenant.id span attribute

• Audit Logs: 2555-day retention in Cloud Logging log bucket, linked to BigQuery for long-term analysis

• Alerts: Email/Slack notifications

Compliance

• GDPR: Data residency and access logging

• HIPAA: Access controls and audit trails

• SOC 2: Identity management and monitoring

• PCI-DSS: Authentication and authorization

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details

Acknowledgments

• Built with MCP SDK

• Powered by Google Cloud BigQuery

• Infrastructure by Terraform

Status: Production Ready Version: 1.0.0 Last Updated: April 2026