BigQuery

What is mcp-bigquery-server?

mcp-bigquery-server is a Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to securely and efficiently interact with Google BigQuery datasets. It acts as a translator, allowing LLMs to query and analyze data in BigQuery using natural language instead of SQL.

How to use mcp-bigquery-server?

There are two main ways to use mcp-bigquery-server:

Option 1: Quick Install via Smithery (Recommended)

1. Ensure you have Node.js 14 or higher, a Google Cloud project with BigQuery enabled, and Claude Desktop installed.
2. Run the following command in your terminal:

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

3. The installer will prompt for your Google Cloud project ID and BigQuery location.
4. Smithery will automatically update your Claude Desktop configuration and restart the application.

Option 2: Manual Setup

1. Authenticate with Google Cloud:
   • Using Google Cloud CLI (development): Run gcloud auth application-default login.
   • Using a service account (production): Save your service account key file and use the --key-file parameter.
2. Add to your Claude Desktop config: Add the following JSON to your claude_desktop_config.json file, replacing your-project-id and optionally your-location and /path/to/service-account-key.json:

   {
     "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"
         ]
       }
     }
   }
   

3. Start chatting! Open Claude Desktop and begin asking questions about your BigQuery 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.

Key Features of mcp-bigquery-server

• Natural Language Querying: Run SQL queries by asking questions in plain English.
• Data Access: Access both tables and materialized views in your BigQuery datasets.
• Schema Exploration: Explore dataset schemas with clear labeling of resource types.
• Safe Data Analysis: Analyze data within safe limits (1GB query limit by default).
• Secure Access: Provides read-only access to ensure data security.

Use Cases of mcp-bigquery-server

• Business Intelligence: Business users can get insights from BigQuery data without needing SQL knowledge.
• Data Exploration: Data analysts can quickly explore datasets using natural language.
• AI-Powered Applications: Developers can integrate BigQuery data access into LLM-powered applications.

FAQ about mcp-bigquery-server

Q: What are the prerequisites for using mcp-bigquery-server? A: Node.js 14 or higher, a Google Cloud project with BigQuery enabled, either Google Cloud CLI installed or a service account key file, and Claude Desktop.

Q: What are the current limitations of mcp-bigquery-server? A: MCP support is currently only available in Claude Desktop (developer preview), connections are limited to local MCP servers, queries are read-only with a 1GB processing limit, and some complex view types might have limitations.

Q: What permissions are needed for mcp-bigquery-server? A: You'll need either roles/bigquery.user or both roles/bigquery.dataViewer and roles/bigquery.jobUser.

Q: Can I contribute to mcp-bigquery-server? A: Yes, you can set up a developer environment by cloning the repository, installing dependencies, and building the project. You can then point your Claude Desktop config to your local build.

BigQuery MCP Server

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:

1. Set up authentication (see below)
2. Add your project details to Claude Desktop's config file
3. 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:

1. 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
     

2. 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"
           ]
         }
       }
     }
     

3. 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 💬

• 🐛 Report issues
• 💡 Feature requests
• 📖 Documentation

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.