BigQuery Data Interface via MCP

System Overview 🤔

This component operates as a dedicated server, allowing Large Language Models (LLMs), such as Claude, to interface directly with your existing BigQuery infrastructure. It functions as a secure intermediary, translating natural language requests into actionable database queries, ensuring secure and optimized data exchange.

Illustrative Exchange

text User Prompt: "Identify the top ten clientele from the prior month." LLM Response: Executes necessary BigQuery interaction and returns the analysis in plain language.

Eliminate the need for manual Structured Query Language (SQL) generation; engage your data assets conversationally.

Operational Mechanics 🛠️

This service leverages the Model Context Protocol (MCP), which establishes a standardized communication framework for AI-database integration. While MCP supports broad model compatibility, initial developer deployment is integrated within the Claude Desktop environment.

The integration process requires: 1. Establishing requisite authentication credentials (detailed below). 2. Integrating project metadata into the Claude Desktop configuration file. 3. Initiating natural language data querying via the interface.

Capabilities Summary 📊

• Conversion of vernacular inquiries into executable SQL operations.
• Access provisioning for both conventional tables and materialized views within specified datasets.
• Schema exploration with precise delineation of resource classifications (views versus tables).
• Data analysis constrained by defined safety parameters (default processing limit set at 1 Gigabyte).
• Strict enforcement of read-only data access policies to maintain integrity.

Deployment Roadmap 🚀

Prerequisites for Operation

• Runtime environment: Node.js version 14 or newer.
• Active Google Cloud project configured with BigQuery API access.
• Operational proficiency with either Google Cloud CLI or possession of a valid service account key file.
• Access to the Claude Desktop application (current mandatory interface).

Path 1: Automated Deployment via Smithery (Preferred)

Execute the following command to automate the provisioning of the BigQuery MCP Server for Claude Desktop utilizing Smithery:

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

The installation utility will request:

• Your specific Google Cloud Project Identifier.
• The BigQuery regional endpoint (defaults to us-central1).

Upon successful parameter entry, Smithery will automatically revise the Claude Desktop configuration and trigger an application restart.

Path 2: Manual Configuration

For environments requiring bespoke setup or granular oversight:

1. Google Cloud Credential Establishment (Select one method):

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

3. Utilizing a Service Account (Recommended for production deployments): bash # Securely store your service account credential file and specify its path using --key-file # Critical: Ensure service account key files are never committed to version control repositories.

4. Configuration Injection into Claude Desktop 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 with Service Account Path:

   { "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 Interaction! Launch Claude Desktop and begin posing queries against your data assets.

Command Line Parameters

This server accepts the following invocation arguments: - --project-id: (Mandatory) Specification of the Google Cloud project identifier. - --location: (Optional) The designated BigQuery operational region; defaults to 'us-central1'. - --key-file: (Optional) Absolute filesystem path to the service account credential JSON artifact.

Service account execution example: bash npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json

Required IAM Roles

One of the following IAM role sets must be granted to the service identity: - roles/bigquery.user (Recommended minimum) - OR the combination of: - roles/bigquery.dataViewer - roles/bigquery.jobUser

Developer Environment Setup (Optional) 🔧

For modification or internal contribution purposes:

bash

Repository Cloning and Dependency Installation

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

Compilation Step

npm run build

Update your Claude Desktop configuration to reference the locally compiled output:

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

• MCP integration is presently restricted to the Claude Desktop client (developer preview status).
• Connectivity is confined to local MCP instances executing on the host machine.
• Queries are subject to strict read-only access and a 1GB data processing ceiling.
• While compatibility spans views and tables, highly intricate view definitions may encounter functional limitations.

Support Channels & Documentation 💬

• 🐛 Submit Defects
• 💡 Propose Enhancements
• 📖 Reference Material

Licensing Terms 📝

Distributed under the MIT License. Refer to the LICENSE file for specifics.

Principal Developer ✍️

Salih Ergüt

Project Sponsorship

This initiative receives dedicated sponsorship from:

Revision Chronicle 📋

Consult [CHANGELOG.md] for granular update records.