Bigquery MCP

A Model Context Protocol (MCP) server designed for BigQuery that helps AI agents obtain database content information to optimize SQL queries.

Database Developer tools #BigQuery tools #AI assistance #Data context #SQL optimization .Python

rating : 2 points

downloads : 4

update time : 2025-04-28

What is the BigQuery MCP server?

The BigQuery MCP server is a context protocol service specifically designed for AI agents. It helps AI better understand the database and generate accurate SQL queries by providing information about the structure and content of the data warehouse.

How to use the BigQuery MCP server?

After installing the necessary tools, you can start the server through a simple command line, and then configure and use it in AI development environments that support MCP, such as Cursor IDE.

Applicable scenarios

It is particularly suitable for scenarios where AI agents are required to perform data analysis and generate SQL queries, such as business intelligence analysis, data exploration, and report generation.

Main features

Dataset explorationProvide a list and detailed information of all datasets in BigQuery

Table structure analysisDisplay column information, data types, and descriptions of data tables

View query historyAccess historical SQL query records to understand common query patterns

Advantages and limitations

Advantages

Significantly improve the accuracy of SQL generation by AI agents

No need to manually provide database structure documentation

Seamlessly integrate with development tools such as Cursor IDE

Limitations

Currently only supports the BigQuery data warehouse

Requires local development environment configuration

Has a certain threshold for non-technical users

How to use

Install dependent tools

Ensure that the uv and Taskfile tools are installed, which can be installed through package managers such as Homebrew

Clone the repository

Get the project source code locally

Install dependencies

Use the uv tool to install Python dependencies

Configure Cursor IDE

Add the MCP server configuration in the Cursor settings

Usage examples

Data analysis taskThe AI agent needs to analyze user behavior data but does not know the table structure

Report generationAutomatically generate complex reports that involve multiple table associations

Frequently Asked Questions

What kind of permissions are required to use the MCP server?

Does it support other databases?

How to verify that the server is running normally?

Related resources

uv official documentation

Documentation for the Python dependency management tool

Taskfile documentation

Documentation for the task running tool

BigQuery client library

The official Google BigQuery client library

🚀 BigQuery MCP Server

A Model Context Protocol (MCP) server designed for BigQuery.

🚀 Quick Start

Prerequisites

This project and the mcp CLI tool rely on the dependency management tool uv being installed. For example, Homebrew users can run brew install uv to install it. Refer to here for more installation methods.

Currently, this project assumes you can create a BigQuery Client "transparently", which is usually the case when gcloud is installed in the local environment. In other environments, appropriate service account credentials may be required (and set the GOOGLE_APPLICATION_CREDENTIALS environment variable to indicate the location of these credentials to the BigQuery client library).

Development Environment

You also need to install Taskfile. For Homebrew users, you can run brew install go-task to install it. Refer to here for more installation methods.

Quick Start (for Cursor IDE)

Ensure the prerequisites are installed.
Clone this repository.
Run uv sync to install dependencies.
In Cursor Settings > MCP Server, start a server using the following command:

uv run --with mcp --directory /path/to/bigquery-mcp mcp run /path/to/bigquery-mcp/src/server.py

It is recommended to write a context rule in the .cursor/rules/tool-use-rule.mdc file in the project. The Cursor agent needs some instructions to use the tool correctly.

📚 Documentation

AI agents have started to excel at writing code but often encounter difficulties when dealing with data-related tasks. This is due to the coupling between program logic and the actual database content.

More specifically, AI agents often perform poorly in writing SQL queries for analysis tasks. They are capable of writing code, so the problem is not a lack of ability in this area but more due to a lack of knowledge about the content of the database.

This MCP server solves this problem by providing tools that AI agents can use to examine the content of the BigQuery data warehouse (i.e., datasets, tables, columns, query history).