BigQuery MCP Server

A Model Context Protocol (MCP) server for accessing Google BigQuery. This server enables Large Language Models (LLMs) to understand BigQuery dataset structures and execute SQL queries.

Features

Authentication and Connection Management

• Supports Application Default Credentials (ADC) or service account key files
• Configurable project ID and location settings
• Authentication verification on startup

Tools

1. query

   • Execute read-only (SELECT) BigQuery SQL queries
   • Configurable maximum results and bytes billed
   • Security checks to prevent non-SELECT queries

2. list_all_datasets

   • List all datasets in the project
   • Returns an array of dataset IDs

3. list_all_tables_with_dataset

   • List all tables in a specific dataset with their schemas
   • Requires a datasetId parameter
   • Returns table IDs, schemas, time partitioning information, and descriptions

4. get_table_information

   • Get table schema and sample data (up to 20 rows)
   • Support for partitioned tables with partition filters
   • Warnings for queries on partitioned tables without filters

5. dry_run_query

   • Check query validity and estimate cost without execution
   • Returns processing size and estimated cost

Security Features

• Only SELECT queries are allowed (read-only access)
• Default limit of 500GB for query processing to prevent excessive costs
• Partition filter recommendations for partitioned tables
• Secure handling of authentication credentials

Installation

Local Installation

# Clone the repository
git clone https://github.com/yourusername/bigquery-mcp-server.git
cd bigquery-mcp-server

# Install dependencies
bun install

# Build the server
bun run build

# Install command to your own path.
cp dist/bigquery-mcp-server /path/to/your_place

Docker Installation

You can also run the server in a Docker container:

# Build the Docker image
docker build -t bigquery-mcp-server .

# Run the container
docker run -it --rm \
  bigquery-mcp-server \
  --project-id=your-project-id

Or using Docker Compose:

# Edit docker-compose.yml to set your project ID and other options
# Then run:
docker-compose up

MCP Configuration

To use this server with an MCP-enabled LLM, add it to your MCP configuration:

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",
        "your-project-id",
        "--location",
        "asia-northeast1",
        "--max-results",
        "1000",
        "--max-bytes-billed",
        "500000000000"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
      }
    }
  }
}

You can also use Application Default Credentials instead of a service account key file:

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",