@qybbs/custom-bigquery-mcp

A standalone Model Context Protocol (MCP) server for Google Cloud BigQuery with enterprise FinOps guardrails, query cost estimation, and strict table allowlisting.

Quick Start via GitHub (Zero Installation)

You can run this MCP server directly without cloning or publishing to npm:

# Set your GCP credentials
export GCP_PROJECT_ID="your-project-id"
export ALLOWLIST_TABLES="project.dataset.table1,dataset.table2"

# Run directly via GitHub using npx
npx -y github:qybbs/custom-bigquery-mcp

Integration with saas-to-mcp-gateway

Add to your gateway-mcp-config.json:

"bigquery": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "github:qybbs/custom-bigquery-mcp"],
  "env": {
    "GCP_PROJECT_ID": "${GCP_PROJECT_ID}",
    "GCP_KEY_FILE_PATH": "${GCP_KEY_FILE_PATH}",
    "ALLOWLIST_TABLES": "${ALLOWLIST_TABLES}",
    "MAX_BYTES_BILLED": "${MAX_BYTES_BILLED}",
    "ROW_LIMIT": "${ROW_LIMIT}"
  }
}

Integration with Claude Desktop / Cursor MCP

{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": ["-y", "github:qybbs/custom-bigquery-mcp"],
      "env": {
        "GCP_PROJECT_ID": "your-project-id",
        "ALLOWLIST_TABLES": "dataset.table1"
      }
    }
  }
}

Related MCP server: BigQuery MCP Server

Features

• Strict FinOps Guardrails: Enforces query dry-runs, comment stripping, SQL AST validation, and blocks mutative keywords (INSERT, UPDATE, DELETE, DROP, ALTER).

• Table Allowlisting: Restricts queries strictly to tables explicitly listed in ALLOWLIST_TABLES.

• Dual Authentication: Supports Google Cloud Application Default Credentials (ADC) or Service Account Key file.

• Cross-Project Access: Automatically configures userProject so queries and metadata extraction across different GCP projects (e.g. shared VPC datasets) are billed to your designated execution project.

• Cost Protection: Hard query caps (MAX_BYTES_BILLED) and client-side retrieval limits (ROW_LIMIT).

Tools Exposed

1. list_allowed_tables: List all BigQuery tables allowed for query execution.

2. describe_table: Get detailed schema, field descriptions, clustering, and partitioning info.

3. estimate_query_cost: Perform dry-run calculation returning scanned bytes and estimated USD cost.

4. execute_readonly_query: Execute read-only SQL queries against allowed tables.

5. search_allowed_tables: Search allowed tables and schemas by keyword.

Environment Configuration

Configure via .env or pass via MCP driver env:

GCP_PROJECT_ID=your-billing-project-id
# GCP_KEY_FILE_PATH=./google-service-account.json (leave commented to use ADC)
ALLOWLIST_TABLES=project.dataset.table1,dataset.table2
MAX_BYTES_BILLED=10737418240
ROW_LIMIT=1000

Local Development & Testing

# Install dependencies
npm install

# Build
npm run build

# Run unit tests
npm test

# Dry-run pack
npm run pack:dry

# Start stdio server locally
npm start

License

MIT License