Nuuly BigQuery MCP Server

This MCP server provides AI code editors with access to Google BigQuery data through the Model Context Protocol (MCP). It allows AI assistants to understand BigQuery datasets and tables, and to run queries against them. This implementation acts as a client that forwards requests to a remote BigQuery MCP server running on Google Cloud Run.

Features

• List available BigQuery datasets
• Get list of tables in a dataset with caching for improved performance
• Get detailed schema information for specific tables in a dataset
• Run SQL queries against BigQuery datasets

Prerequisites

• Python 3.8+

Installation

Step 1: Install Python (Mac Users)

Option A: Using Homebrew (Recommended)

1. Open Terminal
2. Check if Homebrew is installed by typing: brew --version
3. If Homebrew is not installed, install it by copying and pasting this command:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

4. Once Homebrew is installed, install Python:

   brew install python
   

Option B: Download Python directly

1. Go to python.org
2. Download Python 3.8 or newer
3. Run the installer and follow the prompts

Step 2: Install the BigQuery MCP Server

1. Open Terminal
2. Install the server by running:

   pip install nuuly-bigquery-mcp-server
   

3. Wait for the installation to complete

Step 3: Find the Installation Path

You'll need to find where the server was installed to configure Claude:

1. In Terminal, run:

   which nuuly-bigquery-mcp
   

2. This will show something like:
   /Users/yourname/Library/Python/3.12/bin/nuuly-bigquery-mcp
3. Copy this path - you'll need it for the next step

Step 4: Configure Claude Desktop

1. Open Claude Desktop application
2. Find the "MCP Servers" section
3. Click "Edit Config" or open the configuration file
4. Add the following configuration, replacing the path with your actual path from Step 3:

{
  "nuuly-bigquery-mcp": {
    "command": "/Users/yourname/Library/Python/3.12/bin/nuuly-bigquery-mcp",
    "env": {
      "BQ_API_KEY": "D8fzQ2xL9rT7wP6uV3bN1eK5",
      "BIGQUERY_MCP_SERVER_URL": "https://bigquery-mcp-toolbox-oe7jbzhmjq-uk.a.run.app/mcp/invoke"
    }
  }
}

Step 5: Restart Claude

1. Restart Claude Desktop
2. The BigQuery tools should now be available

Available Tools

The server provides the following tools, which are forwarded to the remote BigQuery MCP server:

1. list_databases

Lists all available BigQuery datasets.

list_databases()

2. get_tables

Gets a list of all tables in a specified dataset. Results are cached for improved performance on subsequent calls.

get_tables(database="your_dataset_name")

Example response:

{
  "tables": [
    {
      "name": "table1",
      "full_name": "project.dataset.table1",
      "type": "TABLE"
    },
    {
      "name": "table2",
      "full_name": "project.dataset.table2",
      "type": "TABLE"
    }
  ],
  "count": 2
}

3. get_schema

Gets the detailed schema of a specific table in a dataset.

get_schema(database="your_dataset_name", table="your_table_name")

Example response:

{
  "table": {
    "name": "your_table_name",
    "full_name": "project.your_dataset_name.your_table_name",
    "columns": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE",
        "description": "Unique identifier"
      },
      {
        "name": "created_at",
        "type": "TIMESTAMP",
        "mode": "NULLABLE",
        "description": "Creation timestamp"
      }
    ]
  },
  "success": true
}

4. run_query

Runs a SQL query against a BigQuery dataset.

run_query(database="your_dataset_name", sql="SELECT * FROM your_table LIMIT 10")