🚀 Unleash the Power of LLMs on Your BigQuery Data with MCP! 📊

The Problem: Bridging the Gap Between LLMs and Your Data Warehouse

Large Language Models (LLMs) are revolutionizing how we interact with information. But to truly unlock their potential, they need access to real-world data. Connecting LLMs to databases like BigQuery has traditionally been complex, requiring intricate SQL queries and deep technical expertise.

The Solution: BigQuery MCP Server - Your AI-Powered Data Concierge

The BigQuery MCP Server acts as a seamless intermediary, enabling natural language interaction with your BigQuery data through the Model Context Protocol (MCP). Imagine asking your LLM, "What are our top-selling products this quarter?" and receiving an accurate, insightful answer directly from your BigQuery warehouse – without writing a single line of SQL.

This is the power of the BigQuery MCP Server.

Key Benefits:

Natural Language Data Exploration: Interact with your data using plain English, eliminating the need for complex SQL queries.
Enhanced LLM Capabilities: Provide your LLMs with the context they need to generate more accurate, relevant, and insightful responses.
Simplified Data Access: Democratize data access within your organization, empowering non-technical users to leverage the power of BigQuery.
Secure and Controlled Access: Maintain data security with read-only access and configurable query limits.
Standardized Integration: Leverage the Model Context Protocol (MCP) for a consistent and future-proof integration with various LLMs.

How It Works: A Deep Dive

The BigQuery MCP Server leverages the Model Context Protocol (MCP) to establish a secure and efficient communication channel between your LLM and your BigQuery instance.

Natural Language Query: You pose a question to your LLM in plain English (e.g., "Show me the average order value by region").
MCP Translation: The LLM, using MCP, sends a request to the BigQuery MCP Server.
SQL Generation & Execution: The server intelligently translates the natural language request into an optimized SQL query and executes it against your BigQuery database.
Data Retrieval & Formatting: The server retrieves the results from BigQuery and formats them in a way that the LLM can easily understand.
Intelligent Response: The LLM processes the data and provides you with a clear, concise, and insightful answer.

Getting Started: A Step-by-Step Guide

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)

Installation Options:

Option 1: Smithery - The Easiest Path (Recommended)

Smithery simplifies the installation process with a single command:

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

Smithery will guide you through the configuration process, automatically updating your Claude Desktop settings and restarting the application.

Option 2: Manual Configuration - For Advanced Users

Authentication: Choose your preferred authentication method:
- Google Cloud CLI (Development):
```
gcloud auth application-default login
```
- Service Account (Production):
  - Create a service account with the necessary permissions (see below).
  - Download the service account key file (JSON).
  - Securely store the key file and avoid committing it to version control.

Claude Desktop Configuration: Modify your claude_desktop_config.json file:

Basic Configuration:

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

Service Account Configuration:

{
  "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 begin exploring your data with natural language queries.

Command-Line Arguments:

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

Example (Service Account):

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

Required Permissions:

To ensure secure access, the service account or user needs the following permissions:

roles/bigquery.user (Recommended)
OR both:
- roles/bigquery.dataViewer
- roles/bigquery.jobUser

Advanced Configuration: Developer Setup (Optional)

For customization and contribution:

Clone and Install:

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

Build:
```
npm run build
```

Update Claude Desktop Configuration: Point to 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"
      ]
    }
  }
}

Limitations: Understanding the Boundaries

MCP support is currently limited to Claude Desktop (developer preview).
Connections are restricted to local MCP servers on the same machine.
Queries are read-only with a 1GB processing limit.
Complex view types may have limitations.

Support and Resources: Your Success is Our Priority

License: Open Source Freedom

MIT License - See LICENSE for details.

Author:

Salih Ergüt

Sponsorship:

This project is proudly sponsored by:

Version History:

See CHANGELOG.md for updates and version history.

The Future of Data Interaction is Here

The BigQuery MCP Server is more than just a tool; it's a gateway to a new era of data interaction. By bridging the gap between LLMs and your data warehouse, it empowers you to unlock insights, make data-driven decisions, and transform the way you work with information. Start exploring your data with the power of AI today!

mcp-bigquery-server