BigQuery Natural Language Query Engine

What is this component? 🤔

This server permits your Large Language Models (LLMs), such as Claude, to interface directly with your BigQuery data assets! Envision it as a sophisticated intermediary translator positioned between your intelligent agent and your data warehouse, ensuring secure and high-throughput conversational data access.

Illustrative Scenario

text You: "Identify the top ten clientele from the preceding calendar month." Claude: executes a BigQuery interrogation and furnishes the result in vernacular English

Bypass the need for manual Structured Query Language formulation—simply engage in conversational data exploration!

Operational Mechanism 🛠️

This service leverages the Model Context Protocol (MCP), serving as a standardized communication layer for AI-database interactions. Although MCP is designed for universal AI model compatibility, its current developer preview is accessible exclusively via Claude Desktop.

Implementation Steps: 1. Configure requisite authentication credentials (details follow). 2. Integrate your project parameters into the Claude Desktop configuration manifest. 3. Initiate natural language data interaction.

Functional Capabilities 📊

• Translate plain English inquiries into executable SQL commands for data retrieval.
• Support traversal of both foundational tables and derived materialized views within specified datasets.
• Provide detailed schema navigation, explicitly categorizing resources as tables or views.
• Enforce data governance via a default processing cap (1 Gigabyte query threshold).
• Maintain data integrity through strictly read-only access enforcement.

Initial Setup Guide 🚀

Prerequisites

• Runtime environment: Node.js version 14 or newer.
• A functional Google Cloud environment with BigQuery API enabled.
• Availability of either the Google Cloud CLI or a pre-configured service account credential file.
• The Claude Desktop application (currently the exclusive supported front-end interface).

Method A: Automated Installation via Smithery (Preferred)

To deploy the BigQuery MCP Server for Claude Desktop automatically using Smithery, execute the following command in your terminal environment:

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

The deployment utility will sequentially request:

• Your designated Google Cloud project identifier.
• The BigQuery regional endpoint (defaults to us-central1).

Upon successful configuration, Smithery will automatically synchronize the settings within your Claude Desktop manifest and trigger an application restart.

Method B: Manual Configuration

For scenarios requiring granular control or manual provisioning:

1. Establish Google Cloud Authentication (Select one approach):

2. Utilizing the Google Cloud CLI (Optimal for development workflows): bash gcloud auth application-default login

3. Employing a service account credential (Recommended for production deployments): bash # Securely store your service account key file and reference it using the --key-file flag # Strict adherence to security protocols mandates never committing service account keys to source control repositories

4. Integrate into Claude Desktop Configuration Append the relevant block to your claude_desktop_config.json file:

5. Standard configuration:

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

6. Configuration incorporating a service account file:

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

7. Commence Querying! Launch Claude Desktop and initiate conversational interactions regarding your dataset contents.

Server Command-Line Parameters

The server runtime accepts the following optional/required arguments: - --project-id: (Mandatory) The identifier for your Google Cloud project. - --location: (Optional) The BigQuery operational region; defaults to 'us-central1'. - --key-file: (Optional) Path pointing to the service account credential JSON artifact.

Example invoking service account authentication: bash npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json

Necessary IAM Roles

One of the following role sets must be provisioned: - roles/bigquery.user (Recommended standard permission set) - OR the combination of: - roles/bigquery.dataViewer - roles/bigquery.jobUser

Developer Environment Setup (Optional) 🔧

To facilitate local modification or contribution to the source code:

bash

Repository Cloning and Dependency Installation

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

Compilation/Build Step

npm run build

Subsequently, update your Claude Desktop configuration to direct execution towards your locally built artifact:

{ "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 Operational Constraints ⚠️

• MCP interoperability is presently confined to the Claude Desktop execution environment (developer preview status).
• Connectivity is restricted to local MCP instances residing on the host machine.
• All queries enforce read-only constraints, subject to a 1 GB data processing ceiling.
• While basic tables and views are supported, certain complex view constructs may exhibit functional limitations.

Assistance & Information Channels 💬

• 🐛 Submit Technical Issues
• 💡 Propose New Features
• 📖 Reference Documentation

Software Licensing 📝

MIT License Agreement—Consult the LICENSE file for comprehensive terms.

Creator Acknowledgment ✍️

Salih Ergüt

Project Patronage

This software is supported by:

Chronology of Revisions 📋

Refer to [CHANGELOG.md] for version tracking and update details.