📌Overview

Purpose: The BigQuery MCP Server enables seamless interaction between Large Language Models (LLMs) and BigQuery databases through natural language queries.

Overview: This server acts as a mediator that allows users to engage with their BigQuery data via conversational queries, eliminating the need for manual SQL writing. It integrates with Claude Desktop to provide a user-friendly interface for data exploration.

Key Features:

Natural Language Queries: Users can perform SQL queries simply by asking questions in plain English, making data access more intuitive.
Secure Data Access: Features read-only access to datasets, ensuring data security while allowing exploration of both tables and views.
Schema Exploration: Users can view dataset schemas with clear resource type labels, enhancing their understanding of the data structure.
Query Limitations: Enforced with a 1GB processing limit to maintain performance and prevent resource overuse during data analysis.

BigQuery MCP Server

What is this? 🤔

BigQuery MCP Server is a server that enables your LLMs (like Claude) to communicate directly with your BigQuery data. It acts as a translator between your AI assistant and your database, allowing secure and efficient interactions without manually writing SQL queries.

Quick Example

You: "What were our top 10 customers last month?"
Claude: *queries your BigQuery database and gives you the answer in plain English*

No more writing SQL queries by hand—just chat naturally with your data!

How Does It Work? 🛠️

The server uses the Model Context Protocol (MCP), which serves as a universal translator for AI-database communication. Currently, MCP is available as a developer preview in Claude Desktop.

Steps to use:

Set up authentication
Add your project details to Claude Desktop’s config file
Start chatting with your BigQuery data naturally!

What Can It Do? 📊

Run SQL queries by asking in plain English
Access both tables and materialized views
Explore dataset schemas with clear resource labeling
Analyze data within safe limits (default 1GB query limit)
Ensure data security with read-only access

Quick Start 🚀

Prerequisites

Node.js 14 or higher
Google Cloud project with BigQuery enabled
Google Cloud CLI installed or a service account key file
Claude Desktop (currently the only supported LLM interface)

Option 1: Quick Install via Smithery (Recommended)

Install BigQuery MCP Server for Claude Desktop automatically via Smithery by running:

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

You'll be prompted for:

Your Google Cloud project ID
BigQuery location (defaults to us-central1)

Smithery will update your Claude Desktop configuration and restart the app automatically.

Option 2: Manual Setup

Authenticate with Google Cloud (choose one):
- Using Google Cloud CLI:
```
gcloud auth application-default login
```
- Using a service account (recommended for production): Save your service account key file and use the --key-file parameter.

Add to your Claude Desktop config

Basic configuration:

{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": [
        "-y",
        "@ergut/mcp-bigquery-server",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1"
      ]
    }
  }
}

With service account:

{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": [
        "-y",
        "@ergut/mcp-bigquery-server",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1",
        "--key-file",
        "/path/to/service-account-key.json"
      ]
    }
  }
}

Start chatting!

Open Claude Desktop and start querying your data.

Command Line Arguments

--project-id: (Required) Your Google Cloud project ID
--location: (Optional) BigQuery location, defaults to 'us-central1'
--key-file: (Optional) Path to service account key JSON file

Example using service account:

npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json

Permissions Needed

Required roles:

roles/bigquery.user (recommended)

Or both:

roles/bigquery.dataViewer
roles/bigquery.jobUser

Developer Setup (Optional) 🔧

To customize or contribute locally:

# Clone and install
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm install

# Build
npm run build

Update your Claude Desktop config to use your local build:

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "/path/to/your/clone/mcp-bigquery-server/dist/index.js",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1",
        "--key-file",
        "/path/to/service-account-key.json"
      ]
    }
  }
}

Current Limitations ⚠️

MCP support is only available in Claude Desktop (developer preview)
Connections limited to local MCP servers running on the same machine
Queries are read-only with a 1GB processing limit
Some complex view types may have limitations

Support & Resources 💬

Report issues, feature requests, and documentation at the project’s GitHub repository.

License 📝

MIT License - see LICENSE file for details.

Author ✍️

Salih Ergüt

Sponsorship

This project is proudly sponsored by OREDATA.

Version History 📋

See CHANGELOG.md for updates and version history.