BigQuery MCP server

A Model Context Protocol server that provides access to BigQuery. This server enables LLMs to inspect database schemas and execute queries.

Features:

🔍 Execute SELECT queries on BigQuery datasets
📋 List all accessible tables across datasets
📊 Retrieve detailed table schemas
🔐 Service account authentication support
🎯 Dataset filtering for security and performance
🚀 Dual transport support (stdio for local, HTTP/SSE for cloud deployment)

Deployment Options

This server can be deployed in multiple ways to suit different use cases:

📦 PyPI Package - Install via uvx or uv for local use with Claude Desktop or other MCP clients
🐳 Docker Hub - Pre-built multi-architecture images available at timoschd/mcp-server-bigquery
☁️ Google Cloud Run - Deploy as a serverless HTTP/SSE endpoint with automatic scaling
🔧 Local Development - Use Podman Compose for containerized local development

All deployment methods support both stdio (for local MCP clients) and HTTP/SSE (for cloud/remote access) transports.

Components

Tools

The server implements three tools:

execute-query: Executes a SQL query using BigQuery dialect
- Input: query (string) - SELECT SQL query to execute
- Returns: Query results as a list of dictionaries
list-tables: Lists all tables in the BigQuery database
- Input: None
- Returns: List of fully-qualified table names (format: dataset.table)
describe-table: Describes the schema of a specific table
- Input: table_name (string) - Fully-qualified table name (e.g., my_dataset.my_table)
- Returns: Table DDL (Data Definition Language) with complete schema information

Example Usage

Once connected to an MCP client (like Claude Desktop), you can ask questions like:

"What tables are available in my BigQuery project?"
"Show me the schema for the analytics.user_events table"
"Query the top 10 users by activity from the analytics.user_events table"

The LLM will automatically use the appropriate tools to answer your questions.

Configuration

The server can be configured either with command line arguments or environment variables.

Argument	Environment Variable	Required	Description
`--project`	`BIGQUERY_PROJECT`	Yes	The GCP project ID.
`--location`	`BIGQUERY_LOCATION`	Yes	The GCP location (e.g. `europe-west4`, `us-central1`).
`--dataset`	`BIGQUERY_DATASETS`	No	Only take specific BigQuery datasets into consideration. Several datasets can be specified by repeating the argument (e.g. `--dataset my_dataset_1 --dataset my_dataset_2`) or by joining them with a comma in the environment variable (e.g. `BIGQUERY_DATASETS=my_dataset_1,my_dataset_2`). If not provided, all datasets in the project will be considered.
`--key-file`	`BIGQUERY_KEY_FILE`	No	Path to a service account key file for BigQuery. If not provided, the server will use Application Default Credentials (ADC).
`--transport`	`MCP_TRANSPORT`	No	Transport type: `stdio` (default), `http`, or `sse`. Use `stdio` for local MCP clients, `http`/`sse` for cloud deployments.
`--port`	`PORT` or `MCP_PORT`	No	Port number for HTTP/SSE transport (default: 8080). Ignored when using stdio transport.

Quickstart

Install

Installing via Smithery

To install BigQuery Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-server-bigquery --client claude

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

"mcpServers": {
  "bigquery": {
    "command": "uv",
    "args": [
      "--directory",
      "{{PATH_TO_REPO}}",
      "run",
      "mcp-server-bigquery",
      "--project",
      "{{GCP_PROJECT_ID}}",
      "--location",
      "{{GCP_LOCATION}}"
    ]
  }
}

Published Servers Configuration

"mcpServers": {
  "bigquery": {
    "command": "uvx",
    "args": [
      "mcp-server-bigquery",
      "--project",
      "{{GCP_PROJECT_ID}}",
      "--location",
      "{{GCP_LOCATION}}"
    ]
  }
}

Remote Server Configuration (SSE)

To connect to a remotely deployed server (e.g., on Cloud Run):

"mcpServers": {
  "bigquery": {
    "transport": "sse",
    "url": "https://your-server-url.run.app/messages"
  }
}

Replace {{PATH_TO_REPO}}, {{GCP_PROJECT_ID}}, {{GCP_LOCATION}}, and https://your-server-url.run.app with the appropriate values.

Docker Deployment

The server can be deployed as a Docker container for cloud environments (e.g., Google Cloud Run, Kubernetes).

Docker images are automatically built and published to Docker Hub via GitHub Actions. You can use the pre-built images or build your own.

Using Pre-built Images

# Pull the latest image from Docker Hub
docker pull timoschd/mcp-server-bigquery:latest

# Or pull a specific version
docker pull timoschd/mcp-server-bigquery:v0.3.0

Building Your Own Image

docker build -t mcp-server-bigquery .
# or with Podman
podman build -t mcp-server-bigquery .

The repository includes a GitHub Actions workflow that automatically builds and publishes multi-architecture images (amd64/arm64) to Docker Hub. See .github/workflows/README.md for setup instructions.

Running with Docker

Local stdio mode:

docker run -it \
  -e BIGQUERY_PROJECT=your-project-id \
  -e BIGQUERY_LOCATION=us-central1 \
  timoschd/mcp-server-bigquery:latest

HTTP/SSE mode (for cloud deployment):

docker run -p 8080:8080 \
  -e BIGQUERY_PROJECT=your-project-id \
  -e BIGQUERY_LOCATION=us-central1 \
  -e MCP_TRANSPORT=http \
  -e PORT=8080 \
  timoschd/mcp-server-bigquery:latest

With service account authentication:

docker run -p 8080:8080 \
  -v /path/to/key.json:/app/secrets/key.json \
  -e BIGQUERY_PROJECT=your-project-id \
  -e BIGQUERY_LOCATION=us-central1 \
  -e BIGQUERY_KEY_FILE=/app/secrets/key.json \
  -e MCP_TRANSPORT=http \
  timoschd/mcp-server-bigquery:latest

Using Podman Compose/ Docker Compose

A podman-compose.yml file is provided for easy local development:

# Copy and customize the environment file
cp .env.example .env

# Start the service
podman-compose up

OR

docker-compose up

The compose file supports configurable environment variables:

PORT: External port mapping (default: 8085)
BIGQUERY_PROJECT: Your GCP project ID
BIGQUERY_LOCATION: BigQuery location/region
BIGQUERY_KEY_FILE: Optional path to service account key

Deploying to Google Cloud Run

Manual deployment:

# Build and push to Google Container Registry
gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/mcp-server-bigquery

# Deploy to Cloud Run
gcloud run deploy mcp-server-bigquery \
  --image gcr.io/YOUR_PROJECT_ID/mcp-server-bigquery \
  --platform managed \
  --region us-central1 \
  --set-env-vars BIGQUERY_PROJECT=your-project-id,BIGQUERY_LOCATION=us-central1,MCP_TRANSPORT=http \
  --allow-unauthenticated \
  --port 8080

Automated deployment with GitHub Actions:

An example GitHub Actions workflow is provided for automated deployments. See .github/workflows/README.md for detailed setup instructions.

# Copy the example workflow
cp .github/workflows/deploy-cloud-run.yml.example .github/workflows/deploy-cloud-run.yml

# Configure GitHub Secrets (see workflow README for details)
# Then push to trigger deployment
git push origin main

Development

Building and Publishing

To prepare the package for distribution:

Increase the version number in pyproject.toml
Sync dependencies and update lockfile:

uv sync

Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

Token: --token or UV_PUBLISH_TOKEN
Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

Using MCP Inspector (stdio mode)

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory {{PATH_TO_REPO}} run mcp-server-bigquery --project {{GCP_PROJECT_ID}} --location {{GCP_LOCATION}}

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

Testing HTTP/SSE mode

For testing the HTTP/SSE transport locally:

# Start the server in HTTP mode
uv run mcp-server-bigquery --project {{GCP_PROJECT_ID}} --location {{GCP_LOCATION}} --transport http --port 8080

# In another terminal, test the health endpoint
curl http://localhost:8080/health

Viewing Logs

The server logs to both stdout and /tmp/mcp_bigquery_server.log. When running in Docker:

# View container logs
docker logs <container-id>

# Or access the log file
docker exec <container-id> cat /tmp/mcp_bigquery_server.log

Transport Modes

The server supports two transport modes:

stdio (Default)

Use case: Local MCP clients (Claude Desktop, CLI tools)
Communication: Standard input/output streams
Configuration: Default mode, no additional setup required

HTTP/SSE

Use case: Cloud deployments (Google Cloud Run, Kubernetes, remote servers)
Communication: Server-Sent Events over HTTP
Endpoints:
- GET /: Health check endpoint
- GET /health: Health check endpoint
- GET /messages: SSE connection for receiving events
- POST /messages: Send tool invocation requests
Configuration: Set --transport http or MCP_TRANSPORT=http

Connecting MCP Clients to Remote SSE Server

To connect an MCP client (like Claude Desktop or Windsurf) to a remotely deployed server using SSE transport:

Configuration example (e.g., in mcp_config.json or Claude Desktop config):

{
  "mcpServers": {
    "bigquery": {
      "disabled": false,
      "transport": "sse",
      "url": "https://your-server-url.run.app/messages"
    }
  }
}

Replace https://your-server-url.run.app with your actual deployment URL:

Cloud Run: https://mcp-server-bigquery-xxxxx-uc.a.run.app
Custom domain: https://bigquery-mcp.yourdomain.com
Local testing: http://localhost:8080

The /messages path is required for SSE communication.

Authentication

The server supports multiple authentication methods:

Service Account Key File (Recommended for production):

--key-file /path/to/service-account-key.json
# or
export BIGQUERY_KEY_FILE=/path/to/service-account-key.json

Application Default Credentials (ADC):
- Used automatically when no key file is provided
- Works with gcloud auth application-default login
- Automatically available in Google Cloud environments (Cloud Run, GCE, etc.)

Support

For questions, issues, or feedback:

📧 Email: [email protected]
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.github		.github
src/mcp_server_bigquery		src/mcp_server_bigquery
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
podman-compose.yml		podman-compose.yml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

timoschd/mcp-server-bigquery

Folders and files

Latest commit

History

Repository files navigation

BigQuery MCP server

Deployment Options

Table of Contents

Components

Tools

Example Usage

Configuration

Quickstart

Install

Installing via Smithery

Claude Desktop

Development/Unpublished Servers Configuration

Published Servers Configuration

Remote Server Configuration (SSE)

Docker Deployment

Using Pre-built Images

Building Your Own Image

Running with Docker

Using Podman Compose/ Docker Compose

Deploying to Google Cloud Run

Development

Building and Publishing

Debugging

Using MCP Inspector (stdio mode)

Testing HTTP/SSE mode

Viewing Logs

Transport Modes

stdio (Default)

HTTP/SSE

Connecting MCP Clients to Remote SSE Server

Authentication

Support

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages