mcp-bigquery

Sichere BigQuery-Erkundung über das Model Context Protocol

Dokumentation | Schnellstart | Beispiele

Überblick

mcp-bigquery ist ein Server für das Model Context Protocol (MCP), der es KI-Assistenten (wie Claude) ermöglicht, sicher mit Google BigQuery zu interagieren.

Hauptfunktionen

• Sichere Ausführung: Alle Vorgänge sind strikt auf Dry-Run-Überprüfungen beschränkt. Der Server führt niemals Abfragen aus, die Daten verändern oder Ausführungskosten verursachen.

• Kostentransparenz: Liefert Schätzungen zu Abfragekosten und verarbeiteten Bytes vor der Ausführung.

• Statische Analyse: Analysiert Abfrageabhängigkeiten und validiert die SQL-Syntax.

• Schemaerkundung: Durchsucht Datasets, Tabellen und Spalten.

Geschäftlicher Nutzen

Related MCP server: mcp-bigquery-dryrun

Schnellstart

Schritt 1: Installation

Installieren Sie das Paket über pip:

pip install mcp-bigquery

Schritt 2: Authentifizierung

Richten Sie die Google-Cloud-Plattform-Authentifizierung ein:

# For user account authentication
gcloud auth application-default login

# For service account authentication
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Schritt 3: Claude-Desktop-Konfiguration

Konfigurieren Sie den Server in der Claude-Desktop-Konfigurationsdatei:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Fügen Sie den folgenden Eintrag hinzu:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "your-gcp-project-id"
      }
    }
  }
}

Schritt 4: Überprüfung

Starten Sie Claude Desktop neu und führen Sie die folgenden Abfragen aus, um die Einrichtung zu überprüfen:

• „Welche Datasets sind in meinem BigQuery-Projekt verfügbar?“

• „Können Sie die Kosten schätzen für: SELECT * FROM dataset.table“

• „Zeigen Sie mir das Schema für die Tabelle users an“

Verfügbare Tools

SQL-Validierung und -Analyse

Schemaerkennung

[!IMPORTANT] Das Tool bq_preview_table verwendet client.list_rows (API: tabledata.list), um Beispielzeilen direkt abzurufen, was zu null gescannten Bytes und keinen Ausführungskosten führt. Um eine unbeabsichtigte Offenlegung vertraulicher Informationen (z. B. personenbezogener Daten) gegenüber dem LLM zu verhindern, ist dieses Tool standardmäßig deaktiviert. Sie müssen es explizit aktivieren, indem Sie MCP_BQ_ENABLE_PREVIEW=true in Ihrer Umgebungskonfiguration festlegen.

Konfiguration

Umgebungsvariablen

Beispiel-.env-Datei

Für lokale Tests oder Entwicklungsumgebungen können Sie diese Variablen in einer .env-Datei definieren:

BQ_PROJECT=your-gcp-project-id
BQ_LOCATION=asia-northeast1
SAFE_PRICE_PER_TIB=5.0
LOG_LEVEL=WARNING
MCP_BQ_ENABLE_PREVIEW=true

Vollständiges Konfigurationsbeispiel für Claude Desktop

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "my-production-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "6.0",
        "LOG_LEVEL": "WARNING",
        "MCP_BQ_ENABLE_PREVIEW": "true"
      }
    }
  }
}

Fehlerbehebung

Zugeordnete Fehler und Lösungen

Authentifizierungsfehler

Error: Could not automatically determine credentials

• Lösung: Authentifizieren Sie sich über die Befehlszeile neu:

  gcloud auth application-default login

Zugriff verweigert

Error: User does not have bigquery.tables.get permission

• Lösung: Weisen Sie der Zielidentität die Rolle BigQuery Data Viewer zu:

  gcloud projects add-iam-policy-binding YOUR_PROJECT \
    --member="user:your-email@example.com" \
    --role="roles/bigquery.dataViewer"

Projekt-ID fehlt

Error: Project ID is required

• Lösung: Stellen Sie sicher, dass die Variable BQ_PROJECT in Ihrer Konfiguration korrekt festgelegt ist.

Anwendungsbeispiele

Beispiel 1: Kosten vor der Ausführung prüfen

# Before running an expensive query...
query = "SELECT * FROM `bigquery-public-data.github_repos.commits`"

# First, check the cost
result = bq_dry_run_sql(sql=query)
print(f"Estimated cost: ${result['usdEstimate']}")
print(f"Data processed: {result['totalBytesProcessed'] / 1e9:.2f} GB")

# Output:
# Estimated cost: $12.50
# Data processed: 2500.00 GB

Beispiel 2: Tabellenstruktur verstehen

# Check table schema
result = bq_describe_table(
    dataset_id="your_dataset",
    table_id="users"
)

# Output:
# ├── user_id (INTEGER, REQUIRED)
# ├── email (STRING, NULLABLE)
# ├── created_at (TIMESTAMP, REQUIRED)
# └── profile (RECORD, REPEATED)
#     ├── name (STRING)
#     └── age (INTEGER)

Beispiel 3: Datenabhängigkeiten nachverfolgen

# Understand query dependencies
query = """
WITH user_stats AS (
  SELECT user_id, COUNT(*) as order_count
  FROM orders
  GROUP BY user_id
)
SELECT u.name, s.order_count
FROM users u
JOIN user_stats s ON u.id = s.user_id
"""

result = bq_extract_dependencies(sql=query)

# Output:
# Tables: ['orders', 'users']
# Columns: ['user_id', 'name', 'id']
# Dependency Graph:
#   orders → user_stats → final_result
#   users → final_result

Projektstatus und Versionsverlauf

Entwicklung und Mitwirkung

Anweisungen zur lokalen Entwicklungseinrichtung und zu den Richtlinien für Mitwirkende finden Sie im CONTRIBUTING.md-Leitfaden.

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

# Install development dependencies
pip install -e ".[dev]"

# Execute the test suite
pytest tests/

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Informationen finden Sie in der LICENSE-Datei.