bigquery-mcp

What is bigquery-mcp?

bigquery-mcp is a Model Context Protocol (MCP) server that provides AI agents with tools to examine the contents of a BigQuery data warehouse—including datasets, tables, columns, and query history. It is designed for developers using AI-powered coding tools (e.g., Cursor) to improve the quality of SQL queries by giving the agent context about the database schema and data.

How to use bigquery-mcp?

After ensuring uv is installed and a BigQuery client is available (via gcloud or a service account key set in GOOGLE_APPLICATION_CREDENTIALS), clone the repository and run uv sync. Then, in Cursor settings under MCP Servers, start a server with the command: uv run --with mcp --directory /path/to/bigquery-mcp mcp run /path/to/bigquery-mcp/src/server.py. A contextual rule file (.cursor/rules/tool-use-rule.mdc) is recommended to give the Cursor Agent proper instructions for using the tools.

Key features of bigquery-mcp

• Provides AI agents with tools to list BigQuery datasets, tables, and columns.
• Lets agents inspect query history for context.
• Helps agents write better SQL by exposing database contents.
• Easy integration with Cursor IDE via a single command.
• Relies on uv for dependency management and BigQuery client library for authentication.

Use cases of bigquery-mcp

• An AI coding agent needs to write a query but lacks schema awareness; it uses bigquery-mcp to list all tables and their columns first.
• Exploring a new BigQuery project: an agent can fetch dataset and table names before generating analysis queries.
• Reviewing past query patterns by inspecting BigQuery’s query history through the MCP tools.

FAQ from bigquery-mcp

What prerequisites are required to run bigquery-mcp?

You need uv installed (e.g., via brew install uv) and a BigQuery client that can transparently create a client—usually from having gcloud installed locally. Alternatively, set the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to a service account key.

How do I start bigquery-mcp in Cursor?

In Cursor settings, go to MCP Servers and add a new server with the command: uv run --with mcp --directory /path/to/bigquery-mcp mcp run /path/to/bigquery-mcp/src/server.py.

What tools does bigquery-mcp give to an AI agent?

The server provides tools to examine BigQuery datasets, tables, columns, and query history, giving the agent the context it needs to write better SQL queries.

What are the development dependencies?

For development you also need Taskfile installed (e.g., brew install go-task). The project uses a Taskfile for task automation.

Does bigquery-mcp assume any particular authentication method?

It currently assumes you can transparently create a BigQuery Client. This works when gcloud is installed locally—in other environments you can provide a service account key via the GOOGLE_APPLICATION_CREDENTIALS environment variable.