BigQuery MCP Server

BigQuery MCP Server

これは何ですか？🤔

これは、LLM（Claude など）が BigQuery のデータに直接アクセスできるようにするサーバーです。データウェアハウスへの変更は一切できない、読み取り専用です。 AI アシスタントとデータベースの間に立つ親しみやすい翻訳者のようなもので、安全かつ効率的にやり取りできるようにします。

使用例

You: "What were our top 10 customers last month?"
Claude: *queries your BigQuery database and gives you the answer in plain English*

SQL クエリを手作業で書く必要はもうありません。データに自然な言葉で話しかけるだけです！

どのように動作しますか？🛠️

このサーバーは、AI とデータベースの通信における共通の翻訳者のような Model Context Protocol（MCP）を使用します。MCP は Claude Desktop、Claude Code、および増え続ける他の AI クライアントでサポートされています。

必要な作業は次のとおりです。

1. 認証を設定します（下記を参照）
2. MCP クライアントの設定ファイルにプロジェクトの詳細を追加します
3. BigQuery のデータに自然な言葉で話しかけます！

何ができますか？📊

• 設計上、読み取り専用です — SELECT ステートメントのみが許可されます。すべてのクエリは実行前に BigQuery 独自のドライランプランナーで検証されるため、INSERT、UPDATE、DELETE、DROP、TRUNCATE、EXPORT DATA、MERGE はすべて拒否されます。AI エージェントがデータウェアハウスを変更することは一切できません。
• 平易な英語で質問するだけで SQL クエリを実行します
• データセット内のテーブルとマテリアライズドビューの両方にアクセスします
• リソースの種類（テーブルとビュー）を明確に区別して、データセットのスキーマを調べます
• 設定可能な安全な上限内でデータを分析します（config.json または --maximum-bytes-billed で設定）
• 機密データを保護 — フィールド単位のアクセス制限を定義し、AI エージェントが個人識別情報（PII）、保護対象保健情報（PHI）、財務データ、シークレットを読み取れないようにします。エージェントには、集計や EXCEPT 句を使ってクエリを再構成する方法が明確に示されるため、個々のレコードを公開することなく有用性を保てます。
• 機密フィールドを自動検出 — BigQuery データウェアハウス全体を自動スキャンして、機密パターンに一致する列（氏名、メールアドレス、SSN、医療記録、API キーなど）を検出し、制限リストに追加します。新しいテーブルや列はスキャンのたびに自動的に保護されるため、手作業でのメンテナンスは不要です。
• 柔軟に設定可能 — すべての設定は config.json で管理します。組織独自の命名規則に合わせて検出パターン（例：%guardian_name%、%beneficiary%）を追加したり、スキャン頻度を調整したり、課金上限を設定したり、テーブルごとにフィールド制限を定義したりできます。スキャナーは次回の実行時にカスタムパターンを取り込み、すべてのデータセットで一致する列を自動的に保護します。

どのセットアップが適していますか？

	シンプルモード	保護モード
用途	個人プロジェクト、機密性のないデータ	PHI、PII、財務データ、HIPAA 規制対象環境
インストール	npx — ローカルでのセットアップは不要	npx または config.json を使ったローカルビルド
フィールド制限	なし	preventedFields を定義して機密列をブロック
自動スキャナー	利用不可	すべてのデータセットから機密列を自動検出
セットアップ	以下のクイックセットアップ	以下の保護モードのセットアップ

機密データではローカルデプロイが重要な理由： LLM の推論はクラウドで実行されます。AI エージェントが BigQuery にクエリを実行すると、結果は処理のために LLM プロバイダーのサーバー（Anthropic、OpenAI など）へ送信され、ネットワークの外へ出ます。BigQuery IAM はデータにアクセスできる人を制御しますが、フィールド制限はAI エージェントが LLM の応答に提示する内容を制御します。これらは異なる保護境界です。preventedFields を設定すれば、エージェントが自律的に何度クエリを実行しても、PHI と PII が LLM の会話コンテキストに入ることはありません。

クイックスタート 🚀

前提条件

• Node.js 14 以上
• BigQuery が有効になっている Google Cloud プロジェクト
• Google Cloud CLI がインストールされている、またはサービスアカウントのキーファイルがあること
• MCP 対応クライアント（Claude Desktop、Claude Code など）

クイックセットアップ

1. Google Cloud で認証します：

   gcloud auth application-default login
   

2. MCP クライアントの設定に追加します（例：Claude Desktop の claude_desktop_config.json、Claude Code の .mcp.json）：

   {
     "mcpServers": {
       "bigquery": {
         "command": "npx",
         "args": [
           "-y",
           "@ergut/mcp-bigquery-server",
           "--project-id",
           "your-project-id"
         ]
       }
     }
   }
   

3. チャットを始めましょう！ MCP クライアントを開き、データについて質問します。

保護モードのセットアップ

フィールドレベルの制限が必要な機密データの場合：

1. Google Cloud で認証します（いずれかの方法を選択してください）：

   • Google Cloud CLI を使用する場合（開発に最適）：

     gcloud auth application-default login
     

   • サービスアカウントを使用する場合（本番環境に推奨）：

     # サービスアカウントのキーファイルを保存し、--key-file パラメーターを使用します
     # サービスアカウントのキーファイルは安全に保管し、バージョン管理に絶対にコミットしないでください
     

2. MCP クライアントの設定に追加します（例：Claude Desktop の claude_desktop_config.json、Claude Code の .mcp.json）：

   • Application Default Credentials を使用する場合：

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--config-file",
             "/path/to/config.json"
           ]
         }
       }
     }
     

   • サービスアカウントのキーファイルを使用する場合：

     {
       "mcpServers": {
         "bigquery": {
           "command": "npx",
           "args": [
             "-y",
             "@ergut/mcp-bigquery-server",
             "--project-id",
             "your-project-id",
             "--location",
             "us-central1",
             "--key-file",
             "/path/to/service-account-key.json",
             "--config-file",
             "/path/to/config.json"
           ]
         }
       }
     }
     

3. チャットを始めましょう！ MCP クライアントを開き、データについて質問します。

設定

サーバーでは、高度な設定用に任意の config.json ファイルをサポートしています。設定ファイルがない場合（つまり、--config-file フラグを指定しない場合）、サーバーは安全なデフォルト値（クエリ上限 1GB、フィールド制限なし）でシンプルモードで動作します。保護を有効にするには、サーバーの起動時に --config-file /path/to/config.json を渡してください。

config.json の構造

{
  "maximumBytesBilled": "1000000000",
  "preventedFields": {
    "healthcare.patients": ["first_name", "last_name", "ssn", "date_of_birth", "email"],
    "billing.transactions": ["credit_card_number", "bank_account"]
  },
  "sensitiveFieldPatterns": [
    "%first_name%", "%last_name%", "%email%",
    "%ssn%", "%date_of_birth%", "%password%"
  ],
  "sensitiveFieldScanFrequencyDays": 1
}

設定	デフォルト	説明
maximumBytesBilled	"1000000000" (1GB)	クエリごとの課金対象バイト数の上限
preventedFields	{}	制限対象フィールドのテーブルとカラムの対応付け
sensitiveFieldPatterns	組み込みセット	自動検出用の SQL LIKE パターン
sensitiveFieldScanFrequencyDays	1	自動スキャンの間隔（日数）（0 で無効化）

コマンドライン引数

• --project-id：（必須）Google Cloud プロジェクト ID
• --location：（任意）BigQuery のロケーション。デフォルトは 'US' です
• --key-file：（任意）サービスアカウントのキー JSON ファイルのパス
• --config-file：（任意）設定ファイルのパス。省略した場合、サーバーは保護なしのシンプルモードで動作します。暗黙のデフォルトとして ./config.json が使われることはありません
• --maximum-bytes-billed：（任意）クエリの課金対象バイト数の上限を上書きします。config.json の値より優先されます

サービスアカウントを使用する例：

npx @ergut/mcp-bigquery-server --project-id your-project-id --location europe-west1 --key-file /path/to/key.json --config-file /path/to/config.json --maximum-bytes-billed 2000000000

機密データの保護 🔒

データウェアハウスには、患者の記録、社会保障番号、財務データ、個人の連絡先情報、認証シークレットなど、非常に機密性の高い情報が含まれていることがよくあります。AI エージェントがデータウェアハウスに直接クエリを実行できる場合、機密列の読み取りを防ぐ人間の確認プロセスはありません。SELECT * FROM patients を実行すると、何千件もの PII／PHI レコードが露出する可能性があり、その結果は処理のために LLM プロバイダーへ送信されます。つまり、データはネットワークの外へ出てしまいます。

このサーバーを使うと、管理者は AI エージェントがアクセスできる列をきめ細かく制御できます。config.json で preventedFields を定義すると、サーバーはそれらの列が LLM の応答に含まれるクエリをブロックします。自動スキャナーがすべてのデータセットから機密列を検出するため、データウェアハウスが拡大しても保護範囲を最新の状態に保てます。

**正直な注意点：**フィールド制限は AI エージェント向けの協調的なガードレールであり、悪意ある攻撃者に対する強固な SQL ファイアウォールではありません。脅威モデルの詳細については、PROTECTION.md を参照してください。

このサーバーでは、config.json の protectionMode で設定する 3 つの保護モードを利用できます。

モード	説明
off	保護なし。すべてのテーブルとフィールドにアクセスできます（設定ファイルがない場合のデフォルト）
allowedTables	テーブルの許可リスト。リストに記載されたテーブルのみクエリでき、テーブル内のフィールドも任意で制限できます
autoProtect	データセットを自動スキャンして機密列を検出し、preventedFields を適用します

設定、例、クエリパターンのリファレンス、スキャナーのセットアップ、必要な IAM 権限の詳細については、PROTECTION.md を参照してください。

ローカルビルド（任意） 🔧

npx の代わりにローカルビルドを実行できます。コントリビュート、変更のテスト、または特定のバージョンの実行に便利です。Simple Mode と Protected Mode の両方に対応しています。

# Clone and install
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm install

# Build
npm run build

次に、MCP クライアントの設定でローカルビルドを指定します。

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": [
        "/path/to/your/clone/mcp-bigquery-server/dist/index.js",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1"
      ]
    }
  }
}

Protected Mode の場合は、args 配列に "--config-file", "/path/to/config.json" を追加します（サービスアカウント認証を使う場合は、必要に応じて "--key-file", "/path/to/service-account-key.json" も追加します）。

現在の制限事項 ⚠️

• JSON 設定の例は標準の MCP サーバー形式に準拠しています。MCP 互換のクライアント（Claude Desktop、Claude Code など）で利用できます。正確な設定ファイルの場所については、お使いのクライアントのドキュメントを参照してください。
• 処理上限はクエリごとに設定できます（config.json または --maximum-bytes-billed で設定）。
• テーブルとビューの両方に対応していますが、一部の複雑なビュー形式には制限がある場合があります。
• config.json ファイルは任意です。指定しない場合、サーバーは安全なデフォルト設定を使用します。

サポートとリソース 💬

• 🐛 問題を報告
• 💡 機能をリクエスト
• 📖 ドキュメント

ライセンス 📝

MIT ライセンス — 詳細については LICENSE ファイルを参照してください。

作者 ✍️

Salih Ergüt

スポンサー

このプロジェクトは、以下のスポンサーから支援を受けています。

バージョン履歴 📋

更新内容とバージョン履歴については、CHANGELOG.md を参照してください。