Nuuly BigQuery MCP Server

A Model Context Protocol (MCP) server for BigQuery that allows AI assistants to query and understand BigQuery datasets.

Overview

This MCP server provides a simple interface for AI code editors like Claude Desktop to interact with BigQuery datasets. It connects to the BigQuery toolbox service and provides the following capabilities:

• List available BigQuery datasets
• Retrieve schema information for tables in a dataset
• Execute SQL queries against BigQuery datasets

Installation

Using npx (Recommended)

The simplest way to use the BigQuery MCP server is with npx:

npx nuuly-bigquery-mcp-server start

Installation as a dependency

You can also install the package as a dependency in your project:

npm install nuuly-bigquery-mcp-server

Usage

To start the MCP server:

npx nuuly-bigquery-mcp-server start

Options:

• -p, --port <port>: Port to run the server on (default: 3000)
• -u, --url <url>: BigQuery toolbox URL
• -l, --log-level <level>: Log level (debug, info, warn, error) (default: info)
• -d, --detached: Run in detached mode (background)

To configure the server:

npx nuuly-bigquery-mcp-server config --url http://your-toolbox-url

Additional commands:

# Show current configuration
npx nuuly-bigquery-mcp-server config --show

# Display server information
npx nuuly-bigquery-mcp-server info

# Test connection to BigQuery toolbox service
npx nuuly-bigquery-mcp-server test-connection

Configuration

You can configure the server using environment variables or command-line options:

npx nuuly-bigquery-mcp-server start --port 3000 --url https://your-bigquery-toolbox-url

Or create a .env file in your working directory:

PORT=3000
BIGQUERY_TOOLBOX_URL=https://your-bigquery-toolbox-url
LOG_LEVEL=info

Integration with Claude Desktop

Add the following to your Claude Desktop configuration:

{
  "mcpServers": {
    "Nuuly BigQuery": {
      "command": "npx",
      "args": ["nuuly-bigquery-mcp-server", "start"],
      "env": {}
    }
  }
}

API Documentation

The BigQuery MCP server provides the following tools that can be invoked by AI assistants:

list_databases

Lists all available BigQuery datasets.

Parameters:

• None

Returns:

{
  "databases": [
    {
      "name": "dataset_name",
      "description": "Dataset description",
      "created": "2023-01-01T00:00:00.000Z",
      "updated": "2023-01-01T00:00:00.000Z"
    },
    ...
  ]
}

Example:

{
  "name": "list_databases",
  "arguments": {}
}

get_schema

Retrieves schema information for tables in a specified dataset.

Parameters:

• database (string, required): The name of the BigQuery dataset

Returns:

{
  "tables": [
    {
      "name": "table_name",
      "description": "Table description",
      "columns": [
        {
          "name": "column_name",
          "type": "STRING",
          "description": "Column description",
          "mode": "NULLABLE"
        },
        ...
      ],
      "primaryKeys": ["column_name"],
      "foreignKeys": [
        {
          "columns": ["column_name"],
          "referencedTable": "referenced_table",
          "referencedColumns": ["referenced_column"]
        },
        ...
      ]
    },
    ...
  ]
}

Example:

{
  "name": "get_schema",
  "arguments": {
    "database": "my_dataset"
  }
}

run_query

Executes a SQL query against a BigQuery dataset.

Parameters:

• database (string, required): The name of the BigQuery dataset
• sql (string, required): The SQL query to execute

Returns:

{
  "columns": ["column1", "column2", ...],
  "rows": [
    ["value1", "value2", ...],
    ...
  ],
  "totalRows": 100,
  "executionTime": "1.23 seconds"
}

Example:

{
  "name": "run_query",
  "arguments": {
    "database": "my_dataset",
    "sql": "SELECT * FROM my_table LIMIT 10"
  }
}

Note: For security reasons, only SELECT, SHOW, DESCRIBE, and EXPLAIN statements are allowed.

Examples

The package includes several examples to help you get started:

Example Queries

Check out the examples/queries/basic-queries.md file for a collection of common BigQuery SQL queries, including:

• Simple SELECT queries with filtering
• Aggregation queries with GROUP BY
• JOIN operations between tables
• Date and time functions
• Window functions
• Subqueries
• EXPLAIN statements

Node.js Client

A Node.js example client is provided in examples/node-client.js that demonstrates how to interact with the MCP server programmatically:

# List all databases
node examples/node-client.js list_databases {}

# Get schema for a database
node examples/node-client.js get_schema '{"database": "my_dataset"}'

# Run a query
node examples/node-client.js run_query '{"database": "my_dataset", "sql": "SELECT * FROM my_table LIMIT 10"}'

Python Client

A Python example client is provided in examples/python-client.py:

# List all databases
python examples/python-client.py list

# Get schema for a database
python examples/python-client.py schema my_dataset

# Run a query
python examples/python-client.py query my_dataset "SELECT * FROM my_table LIMIT 10"

Troubleshooting

Connection Issues

Problem: Cannot connect to the BigQuery toolbox service

Solution:

1. Verify that the BigQuery toolbox service is running and accessible
2. Check that the URL is correct in your configuration
3. Run the test-connection command to diagnose issues:

   npx nuuly-bigquery-mcp-server test-connection

SQL Query Errors

Problem: SQL queries are failing or returning errors

Solution:

1. Verify that your SQL syntax is correct
2. Ensure you're only using allowed SQL commands (SELECT, SHOW, DESCRIBE, EXPLAIN)
3. Check that the dataset and table names are correct
4. Try running a simple query first to verify connectivity:

   SELECT 1 as test

MCP Server Not Starting

Problem: The MCP server fails to start

Solution:

1. Check if another process is using the same port
2. Verify that you have the necessary permissions to bind to the port
3. Try specifying a different port:

   npx nuuly-bigquery-mcp-server start --port 3001

4. Increase the log level for more detailed error information:

   npx nuuly-bigquery-mcp-server start --log-level debug

Claude Desktop Integration Issues

Problem: Claude Desktop cannot connect to the MCP server

Solution:

1. Verify that the MCP server is running
2. Check that the Claude Desktop configuration is correct
3. Ensure that the port specified in Claude Desktop matches the one the server is running on
4. Restart Claude Desktop after making configuration changes

Documentation

Detailed documentation is available in the docs directory:

• Installation Guide - Step-by-step instructions for installing and setting up the server
• Configuration Guide - Detailed information about all configuration options
• Troubleshooting Guide - Solutions for common issues
• Integration Guide - Instructions for integrating with Claude Desktop and MCP Inspector

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and delivery:

• CI Workflow: Automatically runs tests, linting, and builds on pull requests and pushes to main
• Release Workflow: Automates version bumping, changelog updates, and npm publishing

To create a new release:

1. Go to the GitHub Actions tab
2. Select the "Release Management" workflow
3. Click "Run workflow"
4. Select the version type (patch, minor, or major)
5. Click "Run workflow"

This will create a new release, update the version in package.json, push tags, and publish to npm.

Development

Setup

# Clone the repository
git clone https://github.com/nuuly/bigquery-mcp-server.git
cd bigquery-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start the server in development mode
npm run dev

Available Scripts

• npm start: Start the server from the compiled JavaScript
• npm run dev: Start the server in development mode using ts-node
• npm run build: Build the TypeScript code
• npm test: Run tests
• npm run lint: Run ESLint

Publishing to npm

To publish the package to npm:

# Log in to npm (you'll need an npm account)
npm login

# Build the package
npm run build

# Publish to npm
npm publish

To update the package:

# Update the version in package.json
npm version patch  # or minor or major

# Publish the updated package
npm publish

License

MIT