# 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:
   ```bash
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
4. Once Homebrew is installed, install Python:
   ```bash
   brew install python
   ```

**Option B: Download Python directly**

1. Go to [python.org](https://www.python.org/downloads/)
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:
   ```bash
   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:
   ```bash
   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:

```json
{
  "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.

```python
list_databases()
```

### 2. get_tables

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

```python
get_tables(database="your_dataset_name")
```

Example response:
```json
{
  "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.

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

Example response:
```json
{
  "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.

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