home / mcp / google bigquery mcp server

Google BigQuery MCP Server

Provides BigQuery access through MCP: datasets, schemas, SQL generation, and query execution

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "garethcull-google-bigquery-mcp": {
      "url": "https://<your-cloud-run-host>/mcp",
      "headers": {
        "MCP_TOKEN": "YOUR_MCP_TOKEN",
        "GOOGLE_AI_KEY": "YOUR_GEMINI_API_KEY",
        "GCP_BQ_BASE64_KEY": "YOUR_BASE64_KEY"
      }
    }
  }
}

This Google BigQuery MCP Server exposes BigQuery datasets, schemas, and SQL execution tools to MCP Clients, enabling natural‑language exploration and querying of your BigQuery projects. It runs as a Flask app and can be used locally or deployed to cloud environments, giving you a flexible way to integrate BigQuery data into conversational workflows.

How to use

Connect an MCP client to the server using either the remote HTTP endpoint or a local stdio setup. Once connected, you can explore your BigQuery project by listing datasets, inspecting table schemas, generating SQL queries with language model assistance, and running those queries after you review the results. The server enforces authorization with a Bearer MCP_TOKEN, so you must include that token in your client requests. Use the four available tools to guide your exploration and to generate and execute queries in a controlled, review‑before‑run flow.

How to install

Prerequisites: you need Python 3.11 or newer and a working Python environment. You will also configure service account credentials and API keys as environment variables before starting the server.

Step 1: Create a virtual environment - Use Python’s venv or your preferred environment manager. - Activate the environment before proceeding.

Step 2: Install dependencies
- In the project directory, install the required modules:
```
pip install -r requirements.txt
```
Note: ensure your environment is active when you run this command.

Step 3: Set environment variables - GCP_BQ_BASE64_KEY: base64‑encoded Google Cloud service account key. - GOOGLE_AI_KEY: Gemini API key for SQL generation. - MCP_TOKEN: token used to authorize requests to the MCP endpoint. - project_id: your BigQuery project id (set in code as needed). Provide the exact values you generate or obtain for your environment.

Step 4: Run the server locally - Start the Flask app in debug/reload mode on a local host and port: ``flask run --debugger --reload -h localhost -p 3000`` - The server exposes an endpoint at /mcp to receive MCP requests.

Additional sections

Security: always require the Authorization header with a Bearer MCP_TOKEN for all /mcp requests. Keep tool outputs reasonably sized and ensure all content is UTF‑8.

Configuration and deployment notes: the server can be deployed to Google Cloud Run or your own infrastructure. When deploying, ensure the necessary environment variables are set in your hosting environment. If you deploy to Cloud Run, you will configure the service to expose a public URL and supply the MCP token for client connections.

Getting started with client connections: you can connect via the remote HTTP endpoint or by using a local stdio configuration. The remote URL is the host where you deploy the server and append /mcp for the JSON‑RPC interface. For local testing, you can run the server and interact with the same /mcp endpoint via a Bearer token.

Available tools

get_list_of_datasets_by_project_id

List all datasets in a given BigQuery project to understand available data sources.

get_table_schema

Inspect the schema of a specified BigQuery table to understand fields and types.

create_custom_sql_query_to_review

Generate a SQL query from natural language input with LM assistance for review before execution.

run_sql_query

Execute a reviewed SQL query against BigQuery and return results.