Bigquery MCP Server

🚀 BigQuery MCP Server

The BigQuery MCP Server is a data server for large language models (LLMs) to access Google BigQuery. This document details the server's features, installation steps, configuration methods, and usage examples.

🚀 Quick Start

The BigQuery MCP Server serves as a data server enabling large language models (LLMs) to access Google BigQuery. This documentation will comprehensively introduce the server's functionalities, installation procedures, configuration methods, and usage examples.

✨ Features

• Query Tool: Supports executing SQL queries and returning results.
• List All Datasets Tool: Returns all datasets in a specified project.
• List All Tables Tool: Returns all tables in a dataset based on the specified dataset ID.
• Get Table Information Tool: Returns table metadata and optional partition information based on the specified dataset and table ID.
• Estimate Query Tool: Estimates the cost of executing a query, including the number of bytes processed and the estimated fee.

📦 Installation

1. Clone the repository

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

2. Install dependencies

   Install using npm or yarn:

   npm install
   # or
   yarn install
   

3. Build the project

   npm run build
   # or
   yarn build
   

4. Start the server

   After the build is complete, run the main file to start the server:

   node dist/index.js
   

📚 Documentation

Environment Variables

The following environment variables are defined in src/utils/args-parser.ts:

• BIGQUERY_PROJECT_ID: Google Cloud project ID (required)
• BIGQUERY_KEY_FILE: Service account key file path (optional)
• BIGQUERY_LOCATION: BigQuery geographical location (default: asia-northeast1)

Configuration File

You can create a .env file in the root directory with the following content:

BIGQUERY_PROJECT_ID=your_project_id
BIGQUERY_KEY_FILE=/path/to/service-account-key.json
BIGQUERY_LOCATION=asia-northeast1

💻 Usage Examples

Query Tool

{
  "query": "SELECT * FROM `project.dataset.table` LIMIT 10",
  "maxResults": 100
}

List All Datasets Tool

// No parameter required

List All Tables Tool

{
  "datasetId": "your_dataset"
}

Get Table Information Tool

{
  "datasetId": "your_dataset",
  "tableId": "your_table",
  "partition": "20250101"
}

Estimate Query Tool

{
  "query": "SELECT * FROM `project.dataset.table` WHERE date = '2025-01-01'"
}

🔧 Technical Details

The server provides detailed error information, including:

• Authentication failure
• Permission issues
• Query syntax errors
• Missing partition filters
• Requests with excessive data processing volume

Code Structure

src/
├── index.ts              # Entry file
├── server.ts             # BigQueryMcpServer class
├── types.ts              # Type definitions
├── tools/                # Tool implementations
│   ├── query.ts          # Query tool
│   ├── list-datasets.ts  # List all datasets tool
│   ├── list-tables.ts    # List all tables tool
│   ├── table-info.ts     # Get table information tool
│   └── dry-run.ts        # Estimate query tool
└── utils/                # Utility functions
    ├── args-parser.ts    # Command-line argument parser
    └── query-utils.ts    # Query validation and response formatting

📄 License

MIT