Overview

This MCP (Model Context Protocol) server exposes Google BigQuery to LLMs and other model-aware tools. It lets model-based agents inspect dataset schemas, list tables, and execute SQL queries against BigQuery using the native BigQuery SQL dialect. The server is intended to be run locally or alongside tools like Claude Desktop, Cursor, or other MCP-aware clients so LLMs can safely and efficiently access your analytics data.

Typical uses include automated data exploration (ask an LLM to describe a table), dynamic query generation and execution, and federating schema metadata into prompts. The server can be scoped to a subset of datasets and configured to use a service account key or default application credentials.

Features

List tables across a project and location
Inspect table schemas (field names, types, nested structures)
Run arbitrary SQL queries using BigQuery dialect
Limit visibility to specific datasets
Configurable credentials: service account key file or default credentials
Optional query timeout to limit long-running jobs
Integrates with MCP-compatible clients (Claude, Cursor, etc.)

Installation / Configuration

Install and run the server as a standalone binary (example uses uvx wrapper shown in project docs). You can set options via CLI flags or environment variables.

Example: CLI invocation

uvx mcp-server-bigquery --project my-gcp-project --location europe-west9 --dataset analytics --key-file ./key.json --timeout 60

Example: equivalent environment variables

export BIGQUERY_PROJECT="my-gcp-project"
export BIGQUERY_LOCATION="europe-west9"
export BIGQUERY_DATASETS="analytics,events"
export BIGQUERY_KEY_FILE="./key.json"
export BIGQUERY_TIMEOUT="60"
uvx mcp-server-bigquery

Configuration reference

Argument	Environment Variable	Required	Description
–project	BIGQUERY_PROJECT	Yes	GCP project ID containing datasets
–location	BIGQUERY_LOCATION	Yes	GCP location/region (e.g. europe-west9)
–dataset	BIGQUERY_DATASETS	No	One or more datasets to expose. Repeat flag or comma-separate in env var
–key-file	BIGQUERY_KEY_FILE	No	Path to a service account JSON key. If omitted uses application default credentials
–timeout	BIGQUERY_TIMEOUT	No	Seconds to wait for queries before timing out. Omit for no timeout

Notes:

To expose multiple datasets via CLI, repeat the flag: –dataset ds1 –dataset ds2
Via environment variable, use comma separation: BIGQUERY_DATASETS=ds1,ds2
If you do not provide a key file, the server will attempt to use default credentials (ADC).

Available Tools

The server exposes the following MCP tools that client LLMs can call:

execute-query: Run a SQL query and return results (supports BigQuery SQL dialect)
list-tables: Return available tables (limited to configured datasets when set)
describe-table: Return the schema for a named table (column names, types, nested fields)

Clients can use these tools programmatically through the MCP transport (stdio, socket, etc.) provided by the client application.

Integrations / Example Client Configs

Claude Desktop example (add to your claude_desktop_config.json):

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": ["mcp-server-bigquery"],
      "env": {
        "BIGQUERY_PROJECT": "{{GCP_PROJECT_ID}}",
        "BIGQUERY_LOCATION": "{{GCP_LOCATION}}"
      }
    }
  }
}

Cursor MCP entry (add under MCP settings similarly):

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": ["mcp-server-bigquery"],
      "env": {
        "BIGQUERY_PROJECT": "{{GCP_PROJECT_ID}}",
        "BIGQUERY_LOCATION": "{{GCP_LOCATION}}"
      }
    }
  }
}

Install via Smithery:

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

Use Cases

Schema discovery: “List columns and types for table analytics.events” — the model calls describe-table and returns structured schema metadata for prompt reasoning.
Natural-language querying: Convert a user question into SQL, run it via execute-query, and summarize results (e.g., “Show top 10 users by spend last 30 days”).
Dataset scoping: Limit the server to specific datasets when exposing data to a shared LLM environment, reducing risk of accidental data leakage.
Automated reporting: Periodically run parameterized queries (via execute-query) and format results for dashboards or emails.

Example workflow (CLI + model):

Ask model to list tables — model invokes list-tables.
Model picks a table and requests schema — model invokes describe-table.
Model synthesizes SQL, calls execute-query, and returns aggregated results.

Security & Best Practices

Prefer granting the server a service account with least privilege (only read/query access to specified datasets).
Use dataset scoping to limit exposure when integrating with shared or external LLMs.
Configure a reasonable timeout to prevent runaway queries and cost surprises.

Repository and source code are available at: https://github.com/LucasHild/mcp-server-bigquery

BigQuery MCP Server: Schema Inspection and Queries