BigQuery MCP Server

What is BigQuery MCP Server about?

Enables LLMs such as Claude to run natural‑language queries against BigQuery tables and materialized views without writing SQL, while enforcing read‑only permissions and a default 1 GB query‑processing limit.

How to use BigQuery MCP Server?

Install via Smithery (recommended) or manually with npx.
Authenticate to Google Cloud – either gcloud auth application-default login for development or a service‑account key for production.
Configure Claude Desktop (or another MCP‑compatible client) by adding the server to the mcpServers section of the config file, supplying --project-id, --location, and optionally --key-file.
Start the server (npx @ergut/mcp-bigquery-server …) and begin asking natural‑language questions; the server translates them into SQL, runs the query, and returns results in plain text.

Key Features

Natural‑language to SQL translation for BigQuery datasets
Read‑only access with a safe 1 GB query limit
Supports both tables and materialized views
Automatic schema exploration with clear labeling of resource types
Simple CLI arguments: --project-id, --location, --key-file
Works with Claude Desktop (developer preview) and any MCP‑compatible client

Use Cases

Business analysts querying sales or customer data without SQL expertise
Automated report generation by LLMs directly from enterprise data warehouses
Secure data exploration in sandbox environments where write access is prohibited
Rapid prototyping of data‑driven AI assistants for internal tooling

FAQ

Q: Which Google Cloud roles are required? A: Either roles/bigquery.user (preferred) or a combination of roles/bigquery.dataViewer and roles/bigquery.jobUser.

Q: Can the server be deployed on a remote machine? A: Currently MCP connections are limited to local servers running on the same machine as the client.

Q: Is there a way to increase the query size limit? A: The limit is fixed at 1 GB for safety in the preview version; changing it would require code modifications and a new release.

Q: Does the server support write operations? A: No. All queries are read‑only to protect data integrity.

Q: What if my view is complex and fails? A: Some advanced view definitions may not be fully supported; consider materializing the view or simplifying the definition.

What is this? 🤔

This is a server that lets your LLMs (like Claude) talk directly to your BigQuery data! Think of it as a friendly translator that sits between your AI assistant and your database, making sure they can chat securely and efficiently.

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? 🛠️

This server uses the Model Context Protocol (MCP), which is like a universal translator for AI-database communication. While MCP is designed to work with any AI model, right now it's available as a developer preview in Claude Desktop.

Here's all you need to do:

Set up authentication (see below)
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 just asking questions in plain English
Access both tables and materialized views in your datasets
Explore dataset schemas with clear labeling of resource types (tables vs views)
Analyze data within safe limits (1GB query limit by default)
Keep your data secure (read-only access)

Quick Start 🚀

Prerequisites

Node.js 14 or higher
Google Cloud project with BigQuery enabled
Either 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)

To install BigQuery MCP Server for Claude Desktop automatically via Smithery, run this command in your terminal:

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

The installer will prompt you for:

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

Once configured, Smithery will automatically update your Claude Desktop configuration and restart the application.

Option 2: Manual Setup

If you prefer manual configuration or need more control:

Authenticate with Google Cloud (choose one method):

Using Google Cloud CLI (great for development):
```
gcloud auth application-default login
```

Using a service account (recommended for production):

# Save your service account key file and use --key-file parameter
# Remember to keep your service account key file secure and never commit it to version control

Add to your Claude Desktop config Add this to your claude_desktop_config.json:

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 asking questions about your data.

Command Line Arguments

The server accepts the following 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

You'll need one of these:

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

Developer Setup (Optional) 🔧

Want to customize or contribute? Here's how to set it up locally:

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

# Build
npm run build

Then update your Claude Desktop config to 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"
      ]
    }
  }
}

Current Limitations ⚠️

MCP support is currently only available in Claude Desktop (developer preview)
Connections are limited to local MCP servers running on the same machine
Queries are read-only with a 1GB processing limit
While both tables and views are supported, some complex view types might have limitations

Support & Resources 💬

License 📝

MIT License - See LICENSE file for details.

Author ✍️

Salih Ergüt

Sponsorship

This project is proudly sponsored by:

Version History 📋

See CHANGELOG.md for updates and version history.

{ "mcpServers": { "bigquery": { "command": "npx", "args": [ "-y", "@ergut/mcp-bigquery-server", "--project-id", "<PROJECT_ID>", "--location", "us-central1", "--key-file", "<PATH_TO_SERVICE_ACCOUNT_KEY_JSON>" ] } } }

BigQuery MCP Server