# GCP BigQuery MCP Server
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io)
[](LICENSE)
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
```bash
# Clone and install dependencies
npm install
# Copy environment configuration
cp .env.example .env
# Build the project
npm run build
```
### Local Development
```bash
# Development mode with hot reload
npm run dev
# Run tests
npm test
# Type checking
npm run typecheck
```
### Production Deployment
```bash
# 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
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** - Health checks, OpenTelemetry tracing, Cloud Monitoring integration
## Documentation
| Document | Description |
|----------|-------------|
| [Usage Guide](docs/USAGE-GUIDE.md) | Complete guide for local dev, testing, and production |
| [Architecture](docs/architecture/) | System design and component documentation |
| [Security](docs/SECURITY.md) | Security middleware and best practices |
| [WIF Guide](docs/wif-architecture.md) | Workload Identity Federation details |
| [Deployment](docs/wif-deployment-guide.md) | Full production deployment guide |
| [Docker](docs/DOCKER-DEPLOYMENT.md) | Container configuration |
| [Monitoring](docs/MONITORING-GUIDE.md) | Observability setup |
| [Documentation Index](docs/README.md) | Complete documentation map |
## Testing
```bash
# 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
```bash
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
- **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!
1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request
## License
MIT License - see [LICENSE](LICENSE) for details
## Acknowledgments
- Built with [MCP SDK](https://github.com/modelcontextprotocol)
- Powered by [Google Cloud BigQuery](https://cloud.google.com/bigquery)
- Infrastructure by [Terraform](https://www.terraform.io)
---
**Status**: Production Ready
**Version**: 1.0.0
**Last Updated**: December 2025
