bigquery

This BigQuery MCP Server provides access to Google BigQuery via the Model Context Protocol (MCP). It exposes a set of tools that allow an LLM to browse datasets, inspect table schemas, run safe read-only queries, and perform dry-run validations to estimate costs before execution. The server supports authentication through Application Default Credentials (ADC) or a service account key file, and it enforces read-only access (only SELECT queries allowed) with sensible defaults to prevent excessive processing.

Available tools include: query (execute read-only SQL with result and cost controls), list_all_datasets (enumerate all datasets in the project), list_all_tables_with_dataset (return tables and their schemas within a dataset), get_table_information (fetch table schema and sample rows with partition awareness), and dry_run_query (validate queries and estimate processing size and cost). These tools enable an LLM to understand data structure, verify queries, and fetch small samples safely before issuing more complex queries.

Prerequisites:

• Node.js or Bun installed on your system (the server is Bun-based but can run in typical Node environments if configured).
• Access to a Google Cloud project with BigQuery API enabled.

Local installation steps:

1. Clone the repository:

git clone https://github.com/yourusername/bigquery-mcp-server.git
cd bigquery-mcp-server

2. Install dependencies (using Bun):

bun install

3. Build the server:

bun run build

4. Run the server (example using Application Default Credentials or a service account key):

# With ADC (no key file path required)
./dist/bigquery-mcp-server --project-id=your-project-id --location=asia-northeast1 --max-results=1000 --max-bytes-billed=500000000000

# With a service account key file
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
./dist/bigquery-mcp-server --project-id=your-project-id --location=asia-northeast1 --max-results=1000 --max-bytes-billed=500000000000

Docker installation (optional):

# Build the Docker image
docker build -t bigquery-mcp-server .

# Run the container (example)
docker run -it --rm \
  bigquery-mcp-server \
  --project-id=your-project-id \
  --location=asia-northeast1 \
  --max-results=1000 \
  --max-bytes-billed=500000000000

Docker Compose (optional):

# docker-compose.yml
version: '3'
services:
  bigquery-mcp:
    image: bigquery-mcp-server
    environment:
      - GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
    command: ["--project-id", "your-project-id", "--location", "asia-northeast1", "--max-results", "1000", "--max-bytes-billed", "500000000000"]

Notes and tips:

• Ensure the service account or ADC has the necessary BigQuery permissions (roles/bigquery.user is recommended; dataViewer and jobUser may be needed for reading data and executing queries).
• The server enforces read-only access by default; attempts to run non-SELECT queries are blocked.
• Use the dry_run_query tool to estimate cost and processing size before running expensive queries.
• When using service account credentials, keep the key file secure and do not commit it to version control.
• The default maximum processing is capped to avoid excessive costs; adjust --max-results and --max-bytes-billed to fit your budget and needs.
• If you encounter authentication issues, verify that the GOOGLE_APPLICATION_CREDENTIALS path is correct and that the file is accessible by the process.
• For large schemas or many datasets, consider listing datasets first to understand your project structure before querying specific tables.