BigQuery

You can run a dedicated MCP server to connect to Google BigQuery, enabling your LLM workflows to understand datasets, list tables, and execute read-only SQL queries securely and cost-effectively.

How to use

Use an MCP client to connect to the BigQuery MCP Server you run locally or in your environment. You can perform read-only operations, such as executing SELECT queries, listing datasets and tables, retrieving table schemas and sample data, and running dry-run checks to estimate costs before execution. The server enforces a read-only mode by only allowing SELECT queries and provides safeguards like a default 500 GB processing limit and partition-filter recommendations for partitioned tables.

Key workflows you can perform include: 1) Run read-only queries against BigQuery tables, 2) List all datasets in your project, 3) List all tables within a dataset along with schemas and descriptions, 4) Retrieve a table’s schema and up to 20 rows of sample data, 5) Dry-run queries to verify validity and estimate cost without executing them.

How to install

Prerequisites: you need a system with Node-compatible tooling or a runtime capable of running the MCP server, and access to a Google Cloud project. You will also configure authentication to BigQuery either with Application Default Credentials or a service account key file.

Local installation steps you can follow end-to-end are below.

# Clone the repository
git clone https://github.com/yourusername/bigquery-mcp-server.git
cd bigquery-mcp-server

# Install dependencies
bun install

# Build the server
bun run build

# Install the built server to your path
cp dist/bigquery-mcp-server /path/to/your_place

Docker and container options

You can also run the server in a Docker container. Build and run with a project ID, or use Docker Compose to configure settings.

# Build the Docker image
docker build -t bigquery-mcp-server .

# Run the container with your project ID
docker run -it --rm \
  bigquery-mcp-server \
  --project-id=your-project-id

# If using Docker Compose, edit the configuration and then start:
docker-compose up

Configuration and environment

Configure the MCP server to point to your Google Cloud project and authentication method. You can choose Application Default Credentials or supply a service account key file. The server supports location and cost controls such as maximum results and maximum bytes billed.

Recommended approaches and tips

• Use Application Default Credentials when you run the server in environments where your Google Cloud credentials are already configured, or supply a service account key file in the environment variable GOOGLE_APPLICATION_CREDENTIALS.

• Keep the default query processing limit at 500 GB to avoid excessive costs unless you have a specific reason to increase it.

Available tools

query

Execute read-only BigQuery SQL queries with optional limits on results and bytes billed; enforces SELECT-only queries for safety.

list_all_datasets

Return an array of dataset IDs within the configured project.

list_all_tables_with_dataset

List all tables in a specified dataset, including schemas, time partitioning, and descriptions.

get_table_information

Provide table schema and a sample of up to 20 rows, with support for partitioned tables and partition filters.

dry_run_query

Validate a query and estimate its cost without executing it, returning processing size and estimated cost.