BigQuery

BigQuery MCP Server lets your AI assistants talk directly to your BigQuery data. It translates natural language questions into SQL, runs queries in a safe, read-only environment, and returns results with clear context about tables, views, and schemas.

How to use

You connect your AI model to the BigQuery MCP Server and start asking questions about your datasets in natural language. The server handles authentication, translates your questions into SQL, executes them against BigQuery, and returns the results in plain language or structured data. You’ll be able to query tables and materialized views, explore schemas, and stay within the 1 GB query limit by default.

How to install

Prerequisites include having 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. Claude Desktop is the current MCP-compatible interface.

Option 1: Quick Install via Smithery (Recommended) To install the 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 (choose one method):

gcloud auth application-default login

Or use 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 config

Add the following to your Claude Desktop configuration to connect to BigQuery via MCP.

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

With service account

If you’re using a service account, 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 start asking questions about your data. The MCP translates your natural language queries into BigQuery SQL behind the scenes and returns results in an accessible format.

Command line arguments

The server accepts the following arguments. Use them when starting the server directly or in your client config.

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

You’ll need one of these BigQuery roles to enable access in read-only mode: either roles/bigquery.user, or both roles/bigquery.dataViewer and roles/bigquery.jobUser.

Available tools

executeQuery

Translate natural language questions into SQL to run against BigQuery and return results

listResources

List tables and materialized views in the connected dataset

inspectSchema

Explore dataset schemas with labels indicating resource types (tables vs views)

dataAnalysis

Analyze data within the 1 GB default query limit and ensure read-only access