Connect your IDE to BigQuery using MCP Toolbox

This guide shows you how to use the MCP Toolbox for Databases to connect your BigQuery instance 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.

This guide demonstrates the connection process for the following IDEs:

Before you begin

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the BigQuery API in the Google Cloud project.

  4. 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 instance.

  5. Configure Application Default Credentials (ADC) for your environment.

Install the MCP Toolbox

  1. 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.6.0 or later:

    linux/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/linux/amd64/toolbox

    darwin/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/arm64/toolbox

    darwin/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/darwin/amd64/toolbox

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/v0.6.0/windows/amd64/toolbox

  2. Make the binary executable:

    chmod +x toolbox

  3. Verify the installation:

    ./toolbox --version

Configure the MCP client

Claude code


1. Install Claude Code.
2. Create .mcp.json file in your project root, if it doesn't exist.
3. 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"
      }
    }
  }
}

Claude desktop


1. Open Claude Desktop and navigate to Settings.
2. In the Developer tab, click Edit Config to open the configuration file.
3. 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"
      }
    }
  }
}

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


Cline


1. Open Cline extension in VS Code and tap MCP Servers icon.
2. Tap Configure MCP Servers to open the configuration file.
3. 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


1. Create the .cursor directory in your project root if it doesn't exist.
2. Create the .cursor/mcp.json file if it doesn't exist and open it.
3. 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"
      }
    }
  }
}

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

Visual Studio Code (Copilot)


1. Open VS Code and create .vscode directory in your project root if it does not exist.
2. Create the .vscode/mcp.json file if it doesn't exist, and open it.
3. Add the following configuration, replace the environment variables with your values, and save: 

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

Windsurf


1. Open Windsurf and navigate to Cascade assistant.
2. Click the MCP icon, then click Configure to open the configuration file.
3. 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"
      }
    }
  }
}

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:

  • execute_sql: execute SQL statement
  • get_dataset_info: get dataset metadata
  • get_table_info: get table metadata
  • list_dataset_ids: list datasets
  • list_table_ids: list tables