bigquery-mcp

Snow Leopard BigQuery MCP

自然言語によるクエリやスキーマの探索を通じて、AI エージェントが BigQuery データベースを操作できるようにする、Google BigQuery 用の Model Context Protocol（MCP）サーバーです。

このプロジェクトは、プラットフォームのベンチマークツールとして Snow Leopard AI が開発したもので、コミュニティが利用・発展させられるよう、公開しています。

MCP とは？

Model Context Protocol（MCP）は、AI アプリケーションが外部のデータソースやツールに安全に接続できるようにするオープン標準です。この BigQuery MCP サーバーは、AI エージェントと BigQuery データセットをつなぐ役割を果たします。

Snow Leopard BigQuery MCP サーバーの機能

リソース

リソース URI	説明
bigquery://tables	エージェントが利用できるすべてのテーブルを一覧表示します
bigquery://tables/{table}/schema	特定のテーブルのスキーマを取得します

ツール

ツール	説明
list_tables(table: str)（任意）	利用可能なテーブルを一覧表示します
get_schema(table: str)（任意）	指定したテーブルのスキーマを取得します
query(sql: str)	BigQuery SQL を実行し、結果を返します

クイックスタート：Claude Desktop

前提条件

始める前に、次のものが用意されていることを確認してください。

• Claude Desktop：こちらからダウンロード
• BigQuery が有効になっている Google Cloud プロジェクト：セットアップガイド
• Google Cloud CLI（gcloud）：インストールガイド
• UV パッケージマネージャー：インストールガイド

1. Google Cloud のセットアップ

まず、Google で認証します。

gcloud auth application-default login

ブラウザーが開き、ローカルマシンを Google Cloud で認証します。

2. Claude Desktop の設定

claude_desktop_config.json ファイルを編集して、BigQuery MCP サーバーを追加します。

アプリケーション：Claude > Settings > Developer > Edit Config
Mac：~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\\Claude\\claude_desktop_config.json

BigQuery ジョブを送信する権限がある Google Cloud プロジェクトを設定する必要があります。BigQuery ジョブを実行できるプロジェクトがない場合は、Google の BigQuery クイックスタートガイド に従ってプロジェクトを作成し、テストしてください。プロジェクトを作成して、公開データセットへのクエリの手順に従います。

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "sl-bigquery-mcp", 
        "--dataset",
        "bigquery-public-data.usa_names",
        "--project",
        "🚨 <projectName> 🚨"
      ]
    }
  }
}

3. Claude Desktop を終了し、ターミナルから起動する

uv のインストール方法によっては、GUI から起動した場合に、uvx 実行ファイルが Claude Desktop の PATH に含まれていないことがあります。uvx が Claude Desktop から利用できることを確実にするため、ターミナルから起動しましょう。

open -a claude

設定を保存したら、Claude Desktop を再起動します。これで、BigQuery のデータについて Claude に質問できるようになります！

クエリの例

What are the top 10 most popular names in 2020?

設定オプション

パラメーターの完全な一覧を確認するには、次を実行します。

uvx sl-bigquery-mcp --help

Usage: sl-bigquery-mcp [OPTIONS]

╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --mode                       [stdio|sse|streamable-http]  MCP transport protocol [default: stdio]                                                     │
│ --dataset                    TEXT                         Dataset(s) for mcp resources. Will create resources for all tables.                         │
│ --table                      TEXT                         Table(s) for mcp resources. Can be specified as project.dataset.table or dataset.table      │
│ --enable-list-tables-tool    --no-enable-list-tables-tool Registers list_resources tool [default: enable-list-tables-tool]                            │
│ --enable-schema-tool         --no-enable-schema-tool      Registers get_schema tool [default: enable-schema-tool]                                     │
│ --project                    TEXT                         BigQuery project [env var: BQ_PROJECT] [default: None]                                      │
│ --api-method                 [INSERT|QUERY]               BigQuery client api_method [default: QUERY]                                                 │
│ --port                       INTEGER                      [default: 8000]                                                                             │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

トラブルシューティング／よくある質問

MCP エラーが発生した場合

まず、より詳細なエラーやログを確認するため、Claude Desktop アプリのログ（設定ファイルと同じディレクトリにあります）を確認してください。

起動時

これは通常、Claude が MCP サーバーの起動に問題を抱えていることを意味します。多くの場合、アプリケーションから uvx にアクセスできないことが原因です。この場合は、claude_desktop_config.json で uvx だけを指定するのではなく、uvx 実行ファイルのフルパスを指定してください。

uv 実行ファイルを見つけるには、次を実行します。

which uvx

それ以外の場合は、引数の誤り、依存関係のバージョンの非互換性、またはバグが原因である可能性があります。後者の 2 つに該当する場合は、問題の内容を記載してissueを登録してください。

リソース／ツールの使用時

MCP サーバーの設定ミス、認証の問題、LLM に渡されるデータが多すぎること、あるいは製品のバグが原因の可能性があります。ログを確認した後、MCP Inspector を使って問題をデバッグすることを検討してください。また、見つけたバグはissue ボードに報告してください。

ローカルでの開発とテスト

開発環境のセットアップ

1. リポジトリをクローンします
2. 仮想環境をセットアップし、依存関係をインストールします
3. インストールを確認します

git clone https://github.com/SnowLeopard-AI/bigquery-mcp.git
cd bigquery-mcp

uv sync
source .venv/bin/activate

sl-bigquery-mcp --help

Google Cloud での認証

次のコマンドを実行すると、Google Cloud アカウントにログインするためのブラウザーが起動します。BigQuery が有効になっている Google Cloud プロジェクトが必要です。プロジェクトがない場合は、Google のbigquery setup guideを参照してください。

gcloud auth application-default login
gcloud config set project <projectName>
gcloud auth application-default set-quota-project <projectName>

テストの実行

開発環境が正しく設定されていることを確認するため、テストを実行します。

pytest tests

注：テストでは公開データセットに対して実際の BigQuery クエリを実行するため、認証が必要です。

ローカルの MCP Inspector

実際に操作しながらテストや開発を行うには、MCP Inspector ツールを使用します。

npx @modelcontextprotocol/inspector uv run sl-bigquery-mcp --dataset bigquery-public-data.usa_names

貢献

皆さまからの貢献を歓迎します！変更をすばやくリポジトリに反映できるよう、discord で事前にご相談ください。コーディングを始める前に連絡を取り合うことで、時間を節約できます。

オープンソースプロジェクトへの貢献に関する手順については、first contributions repositoryを参照してください。

サポート

問題： GitHub Issues
ドキュメント： BigQuery Documentation
MCP プロトコル： Model Context Protocol
お問い合わせ： Discord Server