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 - Follows official MCP SDK best practices
- Security Middleware - Rate limiting, prompt injection detection, data redaction
- Customer-Managed Encryption - CMEK for BigQuery datasets
- Comprehensive Audit Logging - 7-year retention for compliance
- Terraform Infrastructure - Complete IaC for reproducible deployments
- Cloud Run Deployment - Serverless, auto-scaling architecture
- OpenTelemetry - Distributed tracing and metrics
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/ # 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
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
Prerequisites
- GCP Project with billing enabled
- Terraform >= 1.5.0
- Node.js >= 18.0.0
- Docker (for containerization)
Installation
# Clone and install dependencies
npm install
# Copy environment configuration
cp .env.example .env
# Build the project
npm run build
Local Development
# Development mode with hot reload
npm run dev
# Run tests
npm test
# Type checking
npm run typecheck
Production Deployment
# 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 Tools
The server provides these MCP tools:
| Tool | Description |
|---|---|
query_bigquery | Execute SQL queries on BigQuery datasets |
list_datasets | List all available BigQuery datasets |
list_tables | List tables in a specific dataset |
get_table_schema | Get schema information for a table |
Server Capabilities:
- Resources: BigQuery datasets listing
- Tools: Query execution and schema inspection
- 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
- Workload Identity Federation - Identity pools for dev/staging/prod with OIDC providers
- Security Middleware - Rate limiting, prompt injection detection, SQL injection prevention
- BigQuery Integration - Connection pooling, query optimization, dataset discovery
- Monitoring - Health checks, OpenTelemetry tracing, Cloud Monitoring integration
Documentation
| Document | Description |
|---|---|
| Usage Guide | Complete guide for local dev, testing, and production |
| Architecture | System design and component documentation |
| Security | Security middleware and best practices |
| WIF Guide | Workload Identity Federation details |
| Deployment | Full production deployment guide |
| Docker | Container configuration |
| Monitoring | Observability setup |
| Documentation Index | Complete documentation map |
Testing
# 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
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:
- Runs tests on pull requests
- Builds and pushes Docker image
- Deploys to Cloud Run on main branch
- Uses Workload Identity Federation (no keys)
Monitoring
- Cloud Monitoring: Pre-configured dashboards
- Cloud Logging: Structured JSON logs
- Cloud Trace: Distributed tracing via OpenTelemetry
- Audit Logs: 7-year retention in BigQuery
- 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!
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Open a Pull Request
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: December 2025