A secure Model Context Protocol (MCP) server that provides AI assistants with access to Google BigQuery through bearer token authentication, built with Python, FastMCP, and Docker.
This project implements an MCP server that enables AI assistants (like Claude) to interact with Google BigQuery datasets securely. The server uses bearer token authentication and is containerized with Docker for easy deployment.
- 🔐 Secure Authentication: Bearer token authentication for API access
- 🗄️ BigQuery Integration: Execute queries and explore datasets
- 🐳 Containerized: Docker-ready for consistent deployment
- ⚡ Modern Tooling: Built with uv package manager for fast, reliable builds
- 📊 MCP Protocol: Full Model Context Protocol compliance
- Language: Python 3.11+
- Package Manager: uv
- MCP Framework: FastMCP
- BigQuery Client: google-cloud-bigquery v3.38.0+
- Container: Docker + Docker Compose
- Testing: pytest
ProjectMCP/
├── src/mcp_bigquery/ # Main application code
│ ├── server.py # FastMCP server
│ ├── auth.py # Authentication middleware
│ ├── bigquery_client.py # BigQuery wrapper
│ └── config.py # Configuration
├── scripts/ # Utility scripts
│ └── generate_jwt_token.py # JWT token generator for testing
├── tests/ # Test suite
├── docs/ # Documentation
├── Dockerfile # Container definition
├── docker-compose.yml # Orchestration
├── pyproject.toml # Python dependencies
└── README.md # This file
- Python 3.11+
- Docker Desktop
- Google Cloud Project with BigQuery API enabled
- Service Account with BigQuery permissions
- uv package manager
# Install uv
pip install uv
# Clone repository
git clone <repository-url>
cd ProjectMCP
# Install dependencies
uv sync
# Set up environment
cp .env.example .env
# Edit .env with your credentials
# Run with Docker
docker-compose up- QUICKSTART.md - Detailed getting started guide
- tasks.md - Complete implementation task list
- projectbrief.md - Technical architecture and requirements
The server requires the following environment variables:
BEARER_TOKEN=your-secret-token-here
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GCP_PROJECT_ID=your-gcp-project-id
LOG_LEVEL=INFOOnce running, the server provides these MCP tools:
execute_query- Execute SQL queries on BigQuerylist_datasets- List all available datasetslist_tables- List tables in a datasetget_table_schema- Retrieve table schema information
# Run tests
uv run pytest
# Run with coverage
uv run pytest --cov=src/mcp_bigquery
# Format code
uv run black src/ tests/
# Type checking
uv run mypy src/
# Generate JWT tokens and save keys to files
uv run python scripts/generate_jwt_token.py --public-key-file public_key.pem --private-key-file private_key.pem --token-file token.txt
# View help for all options
uv run python scripts/generate_jwt_token.py --helpSee tasks.md for detailed progress tracking.
Current Status: 🔴 Planning Phase
- ⏳ Phase 1: Project Setup (0/2 complete)
- ⏳ Phase 2: Core Implementation (0/4 complete)
- ⏳ Phase 3: Containerization (0/3 complete)
- ⏳ Phase 4: Testing (0/3 complete)
- ⏳ Phase 5: Documentation (0/3 complete)
- ⏳ Phase 6: Security & Quality (0/2 complete)
- ⏳ Phase 7: Release (0/2 complete)
- Bearer tokens should be 32+ characters and randomly generated
- Service account credentials should never be committed to version control
- Use principle of least privilege for BigQuery permissions
- All authentication attempts are logged
- Docker containers run as non-root user
[Add your license here]
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
[Add your contact information]
Status: This project is in planning/development phase. See tasks.md for current progress.