Use BigQuery with MCP, Gemini CLI, and other agents

This guide shows you how to use the MCP Toolbox for Databases to connect your BigQuery project to a variety of Integrated Development Environments (IDEs) and developer tools. It uses the Model Context Protocol (MCP), an open protocol for connecting large language models (LLMs) to data sources like BigQuery, allowing you to run SQL queries and interact with your project directly from your existing tools.

If you use the Gemini CLI, you can use BigQuery extensions. To learn how, see Develop with Gemini CLI. If you plan to build custom tools for the Gemini CLI, continue reading.

This guide demonstrates the connection process for the following IDEs:

Cursor
Windsurf (formerly Codeium)
Visual Studio Code (Copilot)
Cline (VS Code extension)
Claude desktop
Claude code

Before you begin

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Make sure that billing is enabled for your Google Cloud project.
Enable the BigQuery API in the Google Cloud project.
Configure the required roles and permissions to complete this task. You will need the BigQuery User role (roles/bigquery.user), the BigQuery Data Viewer role (roles/bigquery.dataViewer), or equivalent IAM permissions to connect to the project.
Configure Application Default Credentials (ADC) for your environment.

Install the MCP Toolbox

You don't need to install MCP Toolbox if you only plan to use the BigQuery Gemini CLI extensions, as they bundle the required server capabilities. For other IDEs and tools, follow the steps in this section to install MCP Toolbox.

The toolbox acts as an open-source Model Context Protocol (MCP) server that sits between your IDE and BigQuery, providing a secure and efficient control plane for your AI tools.

Download the latest version of the MCP Toolbox as a binary. Select the binary corresponding to your operating system (OS) and CPU architecture. You must use MCP Toolbox version V0.7.0 or later:
linux/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox
Replace VERSION with the MCP Toolbox version—for example v0.7.0.
macOS darwin/arm64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox
Replace VERSION with the MCP Toolbox version—for example v0.7.0.
macOS darwin/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/amd64/toolbox
Replace VERSION with the MCP Toolbox version—for example v0.7.0.
windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox
Replace VERSION with the MCP Toolbox version—for example v0.7.0.
Make the binary executable:
```
chmod +x toolbox
```
Verify the installation:
```
./toolbox --version
```

Set up clients and connections

This section explains how to connect BigQuery to your tools.

If you are using the standalone Gemini CLI, you don't need to install or configure MCP Toolbox, as the extensions bundle the required server capabilities.

For other MCP-compatible tools and IDEs, you must first install MCP Toolbox.

Claude code

Install Claude Code.
Create a .mcp.json file in your project root, if it doesn't exist.

Add the configuration, replace the environment variables with your values, and save:

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

Restart Claude Code to load the new settings. When it reopens, the tool provides an indication that the configured MCP server has been detected.

Claude desktop

Open Claude Desktop and navigate to Settings.
In the Developer tab, click Edit Config to open the configuration file.

Add the configuration, replace the environment variables with your values, and save:

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

Restart Claude Desktop.
The new chat screen displays a hammer (MCP) icon with the new MCP server.

Cline

Open the Cline extension in VS Code and tap the MCP Servers icon.
Tap Configure MCP Servers to open the configuration file.

Add the following configuration, replace the environment variables with your values, and save:

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

A green active status appears after the server connects successfully.

Cursor

Create the .cursor directory in your project root if it doesn't exist.
Create the .cursor/mcp.json file if it doesn't exist and open it.

Add the following configuration, replace the environment variables with your values, and save:

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

Open Cursor and navigate to Settings > Cursor Settings > MCP. A green active status appears when the server connects.

Visual Studio Code (Copilot)

Open VS Code and create a .vscode directory in your project root if it does not exist.
Create the .vscode/mcp.json file if it doesn't exist, and open it.

Add the following configuration, replace the environment variables with your values, and save:

        {
          "servers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

Reload the VS Code window. The MCP-compatible extension automatically detects the configuration and starts the server.

Windsurf

Open Windsurf and navigate to the Cascade assistant.
Click the MCP icon, then click Configure to open the configuration file.

Add the following configuration, replace the environment variables with your values, and save:

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

Note: The BIGQUERY_PROJECT environment variable specifies the default Google Cloud Project ID for the MCP Toolbox to use. All BigQuery operations, such as executing queries, are run within this project.

Use the tools

Your AI tool is now connected to BigQuery using MCP. Try asking your AI assistant to list tables, create a table, or define and execute other SQL statements.

The following tools are available to the LLM:

analyze_contribution: perform contribution analysis, also called key driver analysis.
ask_data_insights: perform data analysis, get insights, or answer complex questions about the contents of BigQuery tables.
execute_sql: execute SQL statement.
forecast: forecast time series data.
get_dataset_info: get dataset metadata.
get_table_info: get table metadata.
list_dataset_ids: list datasets.
list_table_ids: list tables.
search_catalog: search for a table using natural language.

Use BigQuery with MCP, Gemini CLI, and other agents

Before you begin

Install the MCP Toolbox

linux/amd64

macOS darwin/arm64

macOS darwin/amd64

windows/amd64

Set up clients and connections

Claude code

Claude desktop

Cline

Cursor

Visual Studio Code (Copilot)

Windsurf

Use the tools