BigQuery

You can connect Claude Desktop or other MCP clients to your Google Cloud BigQuery data so you can ask questions in plain language and get accurate results. This MCP server acts as a translator between your AI and BigQuery, handling authentication, permissions, and query translation so you can chat with your data safely and efficiently.

How to use

Connect your MCP client to the BigQuery MCP Server and start asking natural language questions about your data. You can ask to run queries, explore dataset schemas, and retrieve results from tables or materialized views. All actions respect read-only access and a 1GB query processing limit by default, with clear labeling of resources (tables vs views) so you understand what you’re querying.

How to install

Prerequisites include Node.js 14 or higher and a Google Cloud project with BigQuery enabled. You also need either the Google Cloud CLI installed or a service account key file, and you should be using Claude Desktop as your MCP client.

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

Option 2: Manual Setup

If you prefer manual configuration or need more control, follow these steps.

1. Authenticate with Google Cloud using either of the methods below.

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 Claude Desktop configuration

Basic configuration for Claude Desktop uses a stdio MCP server invocation with the required project and location details.

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

With service account

If you provide a service account key, include the key file path in the 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 asking questions about your BigQuery data. The MCP server will translate your natural language queries into BigQuery operations and return results in clear, usable formats.

Command line arguments

The server accepts the following arguments. Provide your project ID and optionally choose a location and a service account key file.

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

Permissions needed

You need one of the following roles for BigQuery access in your project.

roles/bigquery.user

OR

roles/bigquery.dataViewer
roles/bigquery.jobUser

Developer setup (Optional) 🔧

If you want to customize or contribute, you can set up the project locally by cloning the repository, installing dependencies, and building.

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

# Build
npm run build

Using a local build with Claude Desktop

If you build locally, point Claude Desktop to your built artifact by updating the MCP server configuration to reference the local index.js path from your dist folder.

{
  "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 available in Claude Desktop as a developer preview. Connections are limited to local MCP servers running on the same machine. Queries are read-only with a 1GB processing limit. Tables and views are supported, but some complex view types might have limitations.

Security and notes

Use read-only access to protect your data. Keep service account keys secure and do not share them. Follow best practices for managing credentials and restrict permissions to what is strictly needed.

Troubleshooting and tips

If you encounter connection issues, verify that you’re using the correct project ID and location, and ensure Claude Desktop is configured to point to your MCP server. Check that the required roles are granted and that your network allows access to Google Cloud services.

Notes

You can explore dataset schemas and see labels that distinguish tables from views. The server enforces a safe operating window with a 1GB query limit and read-only access to protect your data.

Available tools

query_sql

Translate natural language questions into SQL queries against BigQuery and retrieve results.

explore_schema

Explore dataset schemas with labeling of resource types (tables vs views) to understand what data is available.

limit_enforce

Enforce a 1GB query processing limit to protect resources and control costs.

read_only

Ensure all interactions are read-only to prevent data modification.