execute_bigquery_sqlLABSCO SUMMARY
Two servers in one, and you can stop at the first.
The BigQuery half works on its own: read-only queries with maximum_bytes_billed as a cost ceiling, and INSERT, UPDATE, DELETE, CREATE, DROP and ALTER blocked outright. Everything memorable — caching that invalidates on table changes, column documentation, performance history — depends on a Supabase project you set up with the README's schema, so decide up front whether you want that second dependency. Row Level Security and per-user cache isolation are there for multi-tenant use.
What it is
A FastMCP server over BigQuery with an optional Supabase knowledge base behind it. The core is read-only SQL and schema access; the Supabase half adds result caching with dependency-based invalidation, business context on columns, query history and schema-evolution tracking.
What you get
- A read-only SQL query with caching and a cost ceiling —
execute_bigquery_sql, takingsql,maximum_bytes_billed,use_cache,user_idandforce_refresh - Dataset and table discovery with the documentation attached —
get_datasets,get_tables,get_table_schema - Business context rather than just column types —
explain_table, with usage statistics on request - Query recommendations drawn from past usage —
get_query_suggestions - Performance analysis over query history, with recommendations —
analyze_query_performance - Schema changes tracked over time, with impact analysis —
get_schema_changes - Cache operations and a connectivity check —
manage_cachewith actions such asstatsandcleanup, andhealth_check - Three transports from one binary —
mcp-bigquery --transport http,--transport stdio,--transport sse - Server-Sent Events for live monitoring: system status, query execution and resource updates on separate streams
Requirements
Python with uv, installed from a clone as uv pip install -e ".[dev]". BigQuery configuration goes in .env as PROJECT_ID and LOCATION, with KEY_FILE pointing at a service-account key or Google Cloud SDK default credentials used instead. The enhanced features need a Supabase project — SUPABASE_URL plus SUPABASE_SERVICE_KEY or SUPABASE_ANON_KEY — and the tables the README's SQL creates: query_cache, table_dependencies, schema_snapshots, column_documentation, query_history, query_templates, event_log and user_preferences.
Setup effort
Build from source — git clone https://github.com/Mousten/mcp-bigquery-server.git
USE CASES
01
Answering a question without re-billing the same scan
Run the query once and let the cache serve the repeat, with a forced refresh available when the data moved.
02
Understanding a table before you query it
Read the schema with sample values and the business context recorded against its columns.
03
Keeping a runaway query from costing money
Set a bytes-billed ceiling on the call rather than trusting the generated SQL.
04
Finding out why a report got slow
Analyse the query against historical execution patterns and read the recommendations.
05
Tracking a schema that keeps changing
Read the recorded snapshots for a table and see what changed and what it affects.
10 tools
Listed in project docs. Your client may show a different list.
get_datasetsget_tablesget_table_schemaget_query_suggestionsexplain_tableanalyze_query_performanceget_schema_changesmanage_cachehealth_checkBEFORE YOU INSTALL
What to know first
Tools you get
10 tools named in the project's documentation.
Requires
- uv, to install from the clone
- PROJECT_ID (your Google Cloud project) and LOCATION in the client configuration
- BigQuery credentials: a service-account key file named in KEY_FILE, or Google Cloud SDK default credentials (gcloud auth application-default login) with KEY_FILE left out
- Optional, for caching, column documentation and query history: a Supabase project (SUPABASE_URL plus SUPABASE_SERVICE_KEY or SUPABASE_ANON_KEY) with the tables the README creates
INSTALLATION
Connect your client
Server setup
TERMINAL
# Clone the repository
git clone https://github.com/Mousten/mcp-bigquery-server.git
cd mcp-bigquery-server
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"MCP Clients
Claude Desktop — macOS/Linux
CLAUDE DESKTOP — MACOS/LINUX · JSON
{
"mcpServers": {
"mcp-bigquery": {
"command": "<YOUR_PATH_TO_PROJECT>/.venv/bin/mcp-bigquery",
"args": [
"--transport",
"stdio"
],
"env": {
"PROJECT_ID": "<YOUR_PROJECT_ID>",
"LOCATION": "US",
"KEY_FILE": "<YOUR_KEY_FILE>",
"SUPABASE_URL": "https://<YOUR_PROJECT>.supabase.co",
"SUPABASE_SERVICE_KEY": "<YOUR_SUPABASE_SERVICE_KEY>",
"DEFAULT_USER_ID": "<YOUR_DEFAULT_USER_ID>"
}
}
}
}<YOUR_PATH_TO_PROJECT> is the full path of your mcp-bigquery-server clone (the .venv the install step created), and <YOUR_PROJECT_ID> is your Google Cloud project. SUPABASE_URL and SUPABASE_SERVICE_KEY are only for the Supabase features (caching, column documentation, query history) — delete both lines if you have not set up a Supabase project with the README's tables; the server works without Supabase with limited functionality. DEFAULT_USER_ID is optional (the README's .env marks it so); delete it unless you want a default user id for those Supabase features — the tools also take a user_id parameter. KEY_FILE is a service-account key file; to use gcloud auth application-default login instead, delete the KEY_FILE line.
Claude Desktop — Windows
CLAUDE DESKTOP — WINDOWS · JSON
{
"mcpServers": {
"mcp-bigquery": {
"command": "<YOUR_PATH_TO_PROJECT>\\.venv\\Scripts\\mcp-bigquery.exe",
"args": [
"--transport",
"stdio"
],
"env": {
"PROJECT_ID": "<YOUR_PROJECT_ID>",
"LOCATION": "US",
"KEY_FILE": "<YOUR_KEY_FILE>",
"SUPABASE_URL": "https://<YOUR_PROJECT>.supabase.co",
"SUPABASE_SERVICE_KEY": "<YOUR_SUPABASE_SERVICE_KEY>",
"DEFAULT_USER_ID": "<YOUR_DEFAULT_USER_ID>"
}
}
}
}<YOUR_PATH_TO_PROJECT> is the full path of your mcp-bigquery-server clone (the .venv the install step created), and <YOUR_PROJECT_ID> your Google Cloud project. SUPABASE_URL and SUPABASE_SERVICE_KEY are only for the Supabase features (caching, column documentation, query history) — delete both lines if you have not set up a Supabase project with the README's tables; the server works without Supabase with limited functionality. DEFAULT_USER_ID is optional (the README's .env marks it so); delete it unless you want a default user id for those Supabase features — the tools also take a user_id parameter. KEY_FILE is a service-account key file; to use gcloud auth application-default login instead, delete the KEY_FILE line.
