📌Overview

Purpose: The BigQuery MCP server aims to provide seamless access to Google BigQuery, allowing LLMs to work with database schemas and execute queries efficiently.

Overview: This Model Context Protocol server enables interaction with BigQuery, facilitating database operations such as querying and structure inspection. It enhances the capabilities of large language models by integrating them into data querying processes.

Key Features:

• Execute Query: Allows users to run SQL queries using BigQuery's dialect, streamlining data retrieval and manipulation.

• List Tables: Provides a comprehensive list of all tables in the BigQuery database, aiding users in understanding available data sources.

• Describe Table: Offers detailed information about the schema of a specific table, helping users to grasp the structure and types of data they are dealing with.

---

BigQuery MCP Server

A Model Context Protocol server that provides access to BigQuery. This server enables LLMs to inspect database schemas and execute queries.

Components

Tools

The server implements the following tools:

• execute-query: Executes a SQL query using BigQuery dialect
• list-tables: Lists all tables in the BigQuery database
• describe-table: Describes the schema of a specific table

Configuration

The server can be configured with these arguments:

• --project (required): The GCP project ID.
• --location (required): The GCP location (e.g. europe-west9).
• --dataset (optional): Only include specific BigQuery datasets. Multiple datasets can be specified by repeating the argument (e.g. --dataset my_dataset_1 --dataset my_dataset_2). If omitted, all datasets in the project are considered.
• --key-file (optional): Path to a service account key file for BigQuery. If omitted, default credentials are used.

Quickstart

Install

Installing via Smithery

To install BigQuery Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-server-bigquery --client claude

Claude Desktop Configuration

• On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• On Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

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

Published Servers Configuration

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

Replace {{PATH_TO_REPO}}, {{GCP_PROJECT_ID}}, and {{GCP_LOCATION}} with appropriate values.

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

This creates source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Set PyPI credentials via environment variables or command flags:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

MCP servers run over stdio, making debugging challenging. For best experience, use the MCP Inspector.

Launch the MCP Inspector with this command:

npx @modelcontextprotocol/inspector uv --directory {{PATH_TO_REPO}} run mcp-server-bigquery

The Inspector will display a URL to access in your browser to begin debugging.