BigQuery MCP Server

Bu Nedir? 🤔

Bu, LLM'lerinizin (Claude gibi) doğrudan BigQuery verilerinizle konuşmasını sağlayan bir sunucudur — salt okunur, deponuzu değiştirme yeteneği yoktur. Bunu, AI asistanınız ve veritabanınız arasında oturan ve güvenli ve verimli iletişim sağlayan dostça bir çevirmen olarak düşünün.

Hızlı Örnek

Siz: "Geçen ay en iyi 10 müşterimiz kimdi?"
Claude: *BigQuery veritabanını sorgular ve cevabı düz İngilizce olarak verir*

Artık manuel SQL sorguları yazmanıza gerek yok - sadece verilerinizle doğal olarak sohbet edin!

Nasıl Çalışır? 🛠️

Bu sunucu, Model Context Protocol (MCP) kullanır; bu, yapay zeka-veritabanı iletişimi için evrensel bir çevirmen gibidir. MCP, Claude Desktop, Claude Code ve artan sayıda diğer yapay zeka istemcileri tarafından desteklenir.

Yapmanız gereken şeyler:

Kimlik doğrulamayı ayarlayın (aşağıya bakın)
Proje ayrıntılarınızı MCP istemcinizin config dosyasına ekleyin
BigQuery verilerinizle doğal olarak sohbet etmeye başlayın!

Ne Yapabilir? 📊

Tasarım gereği salt okunur — yalnızca SELECT ifadeleri izin verilir. Her sorgu, yürütülmeden önce BigQuery'nin kendi dry-run planlayıcısı tarafından doğrulanır, bu nedenle INSERT, UPDATE, DELETE, DROP, TRUNCATE, EXPORT DATA ve MERGE hepsi reddedilir. AI ajanı deponuzu değiştiremez, nokta.
Basit İngilizce sorularla SQL sorguları çalıştırın
Veri setlerinizde tabloları ve materyalize edilmiş görünümleri erişin
Veri seti şemalarını kaynak türlerinin açık etiketlemesiyle (tablolar vs görünümler) keşfedin
Verileri yapılandırılabilir güvenli limitler içinde analiz edin (config.json veya --maximum-bytes-billed aracılığıyla ayarlayın)
Hassas verileri koruyun — PII, PHI, finansal veri ve sırları okumasını önlemek için alan seviyesi erişim kısıtlamaları tanımlayın. Ajan, bireysel kayıtları açığa çıkarmadan toplam işlevler veya EXCEPT cümlelerini kullanarak sorguları yeniden formüle etme hakkında açık rehberlik alır, bu nedenle faydalı kalır.
Otomatik hassas alan keşfi — tüm BigQuery veri ambarınızı hassas desenleriyle (adlar, e-postalar, SGK numaraları, tıbbi kayıtlar, API anahtarları, vb.) eşleşen sütunlar için otomatik olarak tarayın ve bunları kısıtlanmış listeye ekleyin. Yeni tablolar ve sütunlar her taramada otomatik olarak korunur — manuel bakım gerekmez.
Tam yapılandırılabilir — her şey config.json tarafından kontrol edilir. Kuruluşunuzun adlandırma kurallarına uyacak kendi algılama desenlerinizi ekleyin (ör. %guardian_name%, %beneficiary%), tarama sıklığını ayarlayın, faturalandırma limitlerini belirleyin ve tablo başına alan kısıtlamalarını tanımlayın. Tarayıcı, bir sonraki çalıştırmada özel desenlerinizi alır ve tüm veri setleri arasında eşleşen tüm sütunları otomatik olarak korur.

Hangi Kurulum Sizin İçin Doğru?

	Basit Mod	Korumalı Mod
Ne zaman kullanılır	Kişisel projeler, hassas olmayan veriler	PHI, PII, finansal veriler, HIPAA düzenlenmiş ortamlar
Kurulum	`npx` — yerel kurulum gerekmez	`npx` veya `config.json` ile yerel derleme
Alan kısıtlamaları	Hiçbiri	Hassas sütunları engellemek için `preventedFields` tanımlayın
Otomatik tarayıcı	Kullanılamaz	Tüm veri setleri arasında hassas sütunları otomatik olarak keşfeder
Kurulum	Aşağıdaki Hızlı Kurulum	Aşağıdaki Korumalı Mod Kurulumu

Hassas veriler için yerel dağıtımın neden önemli olduğu: LLM çıkarımı bulutta gerçekleşir. Bir AI ajanı BigQuery'yi sorguladığında, sonuçlar işlenmek üzere LLM sağlayıcısının sunucularına (Anthropic, OpenAI, vb.) gönderilir — ağınızı terk ederler. BigQuery IAM, verilerinize kimin ulaşabileceğini kontrol eder; alan kısıtlamaları, AI ajanının LLM yanıtlarına ne yüzeyleştireceğini kontrol eder. Bunlar farklı koruma sınırlarıdır. preventedFields yapılandırması, PHI ve PII'nin ajanın bağımsız olarak kaç sorgu çalıştırdığından bağımsız olarak LLM konuşma bağlamına asla girmemesini sağlar.

Hızlı Başlangıç 🚀

Ön Koşullar

Node.js 14 veya daha yüksek
BigQuery etkinleştirilmiş Google Cloud projesi
Google Cloud CLI yüklü veya bir hizmet hesabı anahtar dosyası
Herhangi bir MCP uyumlu istemci (Claude Desktop, Claude Code, vb.)

Hızlı Kurulum

Google Cloud ile kimlik doğrulaması yapın:
```
gcloud auth application-default login
```

MCP istemcinizin config dosyasına ekleyin (ör. Claude Desktop için claude_desktop_config.json, Claude Code için .mcp.json):

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

Sohbet etmeye başlayın! MCP istemcinizi açın ve verileriniz hakkında sorular sorun.

Korumalı Mod Kurulumu

Alan seviyesi kısıtlamalarıyla hassas veriler için:

Google Cloud ile kimlik doğrulaması yapın (bir yöntemi seçin):

Google Cloud CLI kullanarak (geliştirme için harika):
```
gcloud auth application-default login
```

Hizmet hesabı kullanarak (üretim için önerilen):

# Hizmet hesabı anahtar dosyanızı kaydedin ve --key-file parametresini kullanın
# Hizmet hesabı anahtar dosyanızı güvenli tutmayı ve asla sürüm kontrolüne vermeyi unutmayın

MCP istemcinizin config dosyasına ekleyin (ör. Claude Desktop için claude_desktop_config.json, Claude Code için .mcp.json):

Application Default Credentials ile:

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

Hizmet hesabı anahtar dosyası ile:

{
  "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"
      ]
    }
  }
}

Sohbet etmeye başlayın! MCP istemcinizi açın ve verileriniz hakkında sorular sormaya başlayın.

Yapılandırma

Sunucu, gelişmiş yapılandırma için opsiyonel bir config.json dosyasını destekler. Config dosyası olmadan (yani --config-file bayrağı olmadan), sunucu güvenli varsayılanlarla Basit Mod'da çalışır (1GB sorgu limiti, alan kısıtlaması yok). Korumayı etkinleştirmek için, sunucuyu başlatırken --config-file /path/to/config.json iletin.

config.json Yapısı

{
  "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
}

Ayar	Varsayılan	Açıklama
`maximumBytesBilled`	`"1000000000"` (1GB)	Sorgu başına maksimum faturalandırılan bayt
`preventedFields`	`{}`	Kısıtlı alanların tablo-sütun eşlemesi
`sensitiveFieldPatterns`	Yerleşik set	Otomatik keşif için SQL LIKE desenleri
`sensitiveFieldScanFrequencyDays`	`1`	Otomatik taramalar arasında günler (devre dışı bırakmak için `0`)

Komut Satırı Argümanları

--project-id: (Gerekli) Google Cloud proje kimliğiniz
--location: (İsteğe bağlı) BigQuery konumu, varsayılan 'US'
--key-file: (İsteğe bağlı) Hizmet hesabı anahtar JSON dosyasının yolu
--config-file: (İsteğe bağlı) Yapılandırma dosyasının yolu. Atlanırsa, sunucu koruma olmadan Basit Mod'da çalışır — ./config.json örtülü varsayılanı yoktur
--maximum-bytes-billed: (İsteğe bağlı) Sorgular için maksimum faturalandırılan baytları geçersiz kılın, config.json değerini geçersiz kılar

Hizmet hesabı kullanma örneği:

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

Hassas Verileri Koruma 🔒

Veri ambarları genellikle oldukça hassas bilgiler içerir — hasta kayıtları, sosyal güvenlik numaraları, finansal veriler, kişisel iletişim ayrıntıları ve kimlik doğrulama sırları. Bir AI ajanı deponuzu sorgulamak için doğrudan erişime sahip olduğunda, hassas sütunları okumasını önlemek için insanın müdahalesi yoktur. Bir SELECT * FROM patients binlerce PII/PHI kaydını açığa çıkarabilir ve sonuçlar daha sonra işlenmek üzere LLM sağlayıcısına gönderilir — ağınızı terk ederler.

Bu sunucu, yöneticilere bir AI ajanının hangi sütunlara erişebileceğinin üzerine ince taneli kontrol verir. config.json'da preventedFields tanımlarsınız ve sunucu bu sütunları LLM yanıtlarına yüzeyleştiren sorguları engeller. Otomatik bir tarayıcı tüm veri setleriniz arasında hassas sütunları keşfeder, bu nedenle kapsam deponuz büyüdükçe güncel kalır.

Dürüst bir uyarı: Alan kısıtlamaları, AI ajanları için işbirliğine dayalı koruma rayları — düşmanca saldırganlar tarafından karşı bir sabit SQL güvenlik duvarı değil. Tam tehdit modeli için PROTECTION.md bakın.

Sunucu, config.json'da protectionMode aracılığıyla ayarlanan üç koruma modunu destekler:

Mod	Açıklama
`off`	Koruma yok — tüm tablolar ve alanlar erişilebilir (config dosyası sağlanmadığında varsayılan)
`allowedTables`	Tablo beyaz listesi — yalnızca listelenen tablolar sorgulanabilir, onların içinde opsiyonel alan kısıtlamalarıyla
`autoProtect`	Veri setlerinizi hassas sütunlar için tarar ve `preventedFields` zorunlu kılar

Tam yapılandırma, örnekler, sorgu deseni referansı, tarayıcı kurulumu ve gerekli IAM izinleri için PROTECTION.md bakın.

Yerel Derleme (İsteğe Bağlı) 🔧

npx yerine yerel derleme çalıştırın — katkıda bulunmak, değişiklikleri test etmek veya sabitlenmiş bir sürüm çalıştırmak için kullanışlı. Hem Basit hem de Korumalı Mod'u destekler.

# Klonlayın ve yükleyin
git clone https://github.com/ergut/mcp-bigquery-server
cd mcp-bigquery-server
npm install

# Derleyin
npm run build

Ardından MCP istemciniz config'ini yerel derlemeye işaret edin:

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

Korumalı Mod için, args dizisine "--config-file", "/path/to/config.json" ekleyin (ve opsiyonel olarak hizmet hesabı kimlik doğrulaması için "--key-file", "/path/to/service-account-key.json").

Mevcut Sınırlamalar ⚠️

JSON yapılandırma örnekleri standart MCP sunucu formatını izler. Herhangi bir MCP uyumlu istemci (Claude Desktop, Claude Code, vb.) bunu kullanabilir — tam config dosyası konumu için istemcinizin belgelerine bakın
İşleme limitleri sorgu başına yapılandırılabilir (config.json veya --maximum-bytes-billed aracılığıyla ayarlayın)
Hem tablolar hem de görünümler desteklenirken, bazı karmaşık görünüm türlerinin sınırlamaları olabilir
Bir config.json dosyası isteğe bağlıdır; biri olmadan sunucu güvenli varsayılanları kullanır

Destek & Kaynaklar 💬

Lisans 📝

MIT Lisansı - Detaylar için LICENSE dosyasına bakın.

Yazar ✍️

Salih Ergüt

Sponsorluk

Bu proje gururla şu tarafından desteklenmektedir:

Sürüm Tarihi 📋

Güncellemeler ve sürüm tarihi için CHANGELOG.md bakın.

ergut/mcp-bigquery-server

Bu MCP sunucusu hakkında