home / mcp / bigquery mcp server

BigQuery MCP Server

A Model Context Protocol server that provides access to BigQuery

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "lucashild-mcp-server-bigquery": {
      "command": "uv",
      "args": [
        "--directory",
        "{{PATH_TO_REPO}}",
        "run",
        "mcp-server-bigquery",
        "--project",
        "{{GCP_PROJECT_ID}}",
        "--location",
        "{{GCP_LOCATION}}"
      ],
      "env": {
        "BIGQUERY_PROJECT": "YOUR_GCP_PROJECT_ID",
        "BIGQUERY_DATASETS": "Optional comma-separated list of datasets",
        "BIGQUERY_KEY_FILE": "Optional path to service account key file",
        "BIGQUERY_LOCATION": "YOUR_GCP_LOCATION"
      }
    }
  }
}

You can run a Model Context Protocol (MCP) server that connects to BigQuery to let large language models inspect database schemas and run queries. This enables conversational AI to discover tables, understand schemas, and execute SQL queries against your BigQuery datasets in a controlled way.

How to use

You interact with the BigQuery MCP server through an MCP client. The server exposes three core actions you can perform against your BigQuery project: list tables to see what exists, describe a table to understand its schema, and execute a query using the BigQuery dialect. When you issue these actions, you receive structured responses that reflect the current state of your BigQuery datasets and the results of your SQL queries.

Typical usage patterns include: listing all tables in a dataset to explore available data, inspecting a specific table’s columns and data types before constructing a query, and running read or analytic queries to retrieve results or feed an LLM’s reasoning with concrete data.

How to install

Prerequisites you need before installation: a working Node.js environment for MCP tooling and access to a GCP project with BigQuery enabled. You should also have the ability to authenticate to Google Cloud using a service account key file if you plan to use a dedicated key.

Install BigQuery MCP server via the MCP tooling used to manage servers. If you are using Claude Desktop or a similar client that bundles MCP tooling, follow the specific steps provided for your client. In many setups, you will run the MCP server with a command that launches the server binary or script via the MCP runtime (such as uv or uvx) and passes your configuration parameters.

Configuration you will provide during setup includes your GCP project ID, location, and optional dataset filters or a key file for authentication. The values you configure are used to connect securely to BigQuery and expose the MCP endpoints to your client.

Development and publishing flows are described in code examples you will follow to run the server locally or deploy it with your MCP runner. These flows show how to start the server with your project and location parameters.

"mcpServers": {
  "bigquery": {
    "command": "uv",
    "args": [
      "--directory",
      "{{PATH_TO_REPO}}",
      "run",
      "mcp-server-bigquery",
      "--project",
      "{{GCP_PROJECT_ID}}",
      "--location",
      "{{GCP_LOCATION}}"
    ]
  }
}

Additional configuration and start options

You can also run a published configuration where the server is started via the MCP runtime without the local development directory reference. In this mode, you would see a setup similar to the following example, which uses the published start flow.

"mcpServers": {
  "bigquery": {
    "command": "uvx",
    "args": [
      "mcp-server-bigquery",
      "--project",
      "{{GCP_PROJECT_ID}}",
      "--location",
      "{{GCP_LOCATION}}"
    ]
  }
}

Available tools

execute-query

Executes a SQL query using the BigQuery dialect against the configured project and dataset.

list-tables

Lists all tables in the configured BigQuery dataset(s) to help you explore available data.

describe-table

Describes the schema of a specific table, including columns and data types.