Bigquery Analysis MCP Server

🚀 BigQuery Analysis MCP Server

This is an MCP server for executing SQL queries on Google BigQuery, offering the following features:

• Query validation (pre - execution): Verify the validity of a query and estimate its processing scale.
• Secure query execution: Only allow SELECT queries processing less than 1TB of data (prevent data modification).
• JSON - formatted results: Return query results in a structured JSON format.

✨ Features

Tools

• dry_run_query - Perform a pre - execution operation for a BigQuery query.

  • Validate the query and estimate its processing scale.
  • Check if the query size meets the 1TB limit.

• run_query_with_validation - Run a BigQuery query with validation.

  • Detect and reject DML statements (data modification queries).
  • Reject queries that process more than 1TB of data.
  • Execute the validated query and return the results.

📦 Installation

To use it on Claude Desktop, add the server configuration:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": ["/path/to/bigquery-server/build/index.js"]
    }
  }
}

Debugging

The MCP server communicates via standard input and output (stdio), so debugging can be challenging. We recommend using MCP Inspector:

npm run inspector

The Inspector will provide a URL to access the debugging tool in the browser.

📚 Documentation

Prerequisites

• Node.js (v16 or higher)
• Google Cloud authentication settings (gcloud CLI or service account)

Install Dependencies

npm install

Build

npm run build

Development Mode (Automatic Rebuild)

npm run watch

🔧 Technical Details

Authentication Settings

This server requires Google Cloud authentication. Please complete the settings using one of the following methods:

1. Log in using the gcloud CLI:

gcloud auth application - default login

2. Use a service account key:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service - account - key.json"

💻 Usage Examples

Basic Usage

dry_run_query("SELECT * FROM `bigquery - public - data.samples.shakespeare` LIMIT 10")

Advanced Usage

run_query_with_validation("SELECT word, word_count FROM `bigquery - public - data.samples.shakespeare` WHERE corpus='hamlet' LIMIT 10")