BigQuery MCP-Server: Remote-Server und MCP Toolbox im Test

Inhalt
Es gibt zwei offizielle Wege, einem KI-Agenten über das Model Context
Protocol (MCP) Zugriff auf BigQuery zu geben. Google betreibt unter
https://bigquery.googleapis.com/mcp einen verwalteten Remote-MCP-Server,
und die Open-Source-Software MCP Toolbox for
Databases (kurz MCP Toolbox)
stellt dieselbe Art von Tools auf Ihrem eigenen Rechner oder Server bereit.
Mit beiden kann der Agent Datasets auflisten, Tabellenschemas lesen und SQL
ausführen. Der Unterschied liegt in der Kontrolle. Die Toolbox kann Abfragen
auf eine Liste erlaubter Datasets beschränken und die abgerechneten Bytes pro
Abfrage deckeln, der Remote-Server verlässt sich auf IAM und kennt keine
Kostengrenze pro Abfrage.
Wir haben am 6. November 2026 beide eingerichtet (MCP Toolbox 1.16.0, MCP
Inspector 2.14.0), MCP Inspector, Claude Code und einen kleinen
Python-Agenten angebunden und den Agenten sieben Geschäftsfragen zum
öffentlichen Dataset bigquery-public-data.thelook_ecommerce beantworten
lassen. Mit klaren Anweisungen beantwortete er über den Remote-Server alle
sieben Fragen richtig, über die Toolbox sechs. Mit einem knappen Prompt waren
es nur vier und fünf. Die Ursachen, ein Parser-Fehler in der Toolbox, eine
erfundene Zahl und eine mehrdeutige Spalte, beschreiben wir unter
"Stolpersteine aus dem Test".
Was ein BigQuery-MCP-Server macht
Ein MCP-Server stellt Tools bereit, die ein KI-Client aufrufen kann. Für BigQuery genügen wenige:
- die Datasets und Tabellen auflisten, die der Aufrufer sehen darf,
- Schema und Beschreibung einer Tabelle lesen,
- eine SQL-Abfrage ausführen und die Zeilen zurückgeben.
Das SQL schreibt der Client. Claude Code, Codex, Gemini CLI oder Ihr eigener Agent übersetzt die Frage in SQL, ruft das Abfrage-Tool auf und formuliert die Antwort. Der Server führt nur aus und liefert Daten. So bleiben die Modellkosten beim Client, und Sie steuern den Zugriff an einer Stelle. Wie MCP funktioniert, erklärt unser Beitrag MCP-Server mit FastMCP erstellen. Wie ein Agent aus einer Frage SQL für BigQuery macht, zeigt Datenbankabfragen in natürlicher Sprache.
Zwei Wege, einen Agenten mit BigQuery zu verbinden: MCP Toolbox auf eigener Infrastruktur oder Googles verwalteter Remote-MCP-Server
Jede Abfrage läuft als normaler BigQuery-Job, abgerechnet über ein Projekt Ihrer Wahl, unter der Identität, die der Server verwendet: dem Token, das der Client mitschickt, oder den eigenen Anmeldedaten der Toolbox. Deshalb ist die Identität die wichtigste Entscheidung. Was dieses Dienstkonto lesen darf, darf auch der Agent lesen.
Die Optionen im Vergleich
| Option | Authentifizierung | Nur-Lesen und Dataset-Grenzen | Kostengrenze pro Abfrage | Aufwand |
|---|---|---|---|---|
| Remote-BigQuery-MCP-Server (Google) | OAuth-Token eines Benutzers oder Dienstkontos, keine API-Keys | Tool execute_sql_readonly, IAM-Deny-Policy für Schreib-Tools, Dataset-Zugriff nur über IAM | keine, nur Tageskontingente | nichts zu installieren |
| MCP Toolbox, vorgefertigte BigQuery-Tools | ADC, Impersonation oder das OAuth-Token des Clients | BIGQUERY_READONLY, keine Allowlist-Variable in der vorgefertigten Konfiguration | BIGQUERY_MAXIMUM_BYTES_BILLED | eine Binärdatei, Umgebungsvariablen |
MCP Toolbox, eigene tools.yaml | wie oben | readOnly, allowedDatasets, feste SQL-Tools | maximumBytesBilled | eine Binärdatei und eine YAML-Datei |
| LucasHild/mcp-server-bigquery 0.3.3 | ADC oder Schlüsseldatei | Dataset-Filter nur beim Auflisten, Abfragen unbeschränkt | keine | Einzeiler mit uvx |
| ergut/mcp-bigquery-server 1.0.4 | ADC oder Schlüsseldatei | nur SELECT (per Dry Run geprüft), optionale Spaltensperren | 1 GB Standard, einstellbar | Einzeiler mit npx |
Die Zeilen zu Googles Optionen stammen aus der offiziellen Dokumentation und
unserem Test, die zu den Community-Servern aus deren READMEs und Quellcode.
Das Tool execute-query von LucasHild führt jedes SQL aus, das es bekommt.
Nur-Lese-Zugriff hängt dort also allein an den Rechten der Identität.
Unsere Empfehlung:
- Für Entwicklerinnen und Entwickler, die aus Claude Code, Cursor oder Gemini CLI Daten erkunden wollen: der Remote-Server. Es läuft nichts bei Ihnen, und IAM weiß bereits, wer was sehen darf.
- Für einen Agenten, der unbeaufsichtigt läuft oder viele Benutzer bedient:
die MCP Toolbox mit eigener
tools.yaml, Dataset-Allowlist und Byte-Grenze, oder ausschließlich feste SQL-Tools. - Community-Server reichen für einen schnellen lokalen Test. Sie schieben aber einen Drittanbieter zwischen Agent und Data Warehouse, ohne Kontrollen zu bieten, die Googles Optionen fehlen.
Schritt 1: ein eigenes Dienstkonto
Lassen Sie einen Agenten nicht mit Ihrem eigenen Konto arbeiten. Legen Sie ein
Dienstkonto an, das im Abrechnungsprojekt Abfrage-Jobs starten und nur die
nötigen Datasets lesen darf. Diese Befehle haben wir ausgeführt (PROJECT_ID
und die E-Mail-Adresse ersetzen):
Unser Test nutzte ein öffentliches Dataset, das jedes Konto lesen darf. Für Ihre eigenen Daten vergeben Sie BigQuery Data Viewer pro Dataset statt auf das ganze Projekt. Die BigQuery-DCL-Referenz zeigt die SQL-Variante:
Für ein Dienstkonto lautet der Empfänger "serviceAccount:<email>". Diese
Freigaben pro Dataset sind die einzige Dataset-Allowlist, die der
Remote-Server kennt.
Statt eine Schlüsseldatei herunterzuladen, erzeugen Sie ein Token, das eine Stunde gilt:
Beide Server akzeptieren dieses Token als Authorization: Bearer ....
Option A: Googles Remote-BigQuery-MCP-Server
Der Remote-Server braucht keine Installation. Laut
Dokumentation
ist er mit der BigQuery API aktiv, spricht Streamable HTTP und verlangt die
Rolle roles/mcp.toolUser zusätzlich zu den üblichen BigQuery-Rollen. Er
bietet neun Tools: list_dataset_ids, get_dataset_info, list_table_ids,
get_table_info, execute_sql_readonly, execute_sql, get_query_results,
cancel_job und get_job. Alle außer execute_sql und cancel_job sind als
Nur-Lese-Tools markiert.
Googles Anleitung für Claude Code arbeitet mit OAuth-Client-ID und -Secret
(dynamische Client-Registrierung unterstützen die Remote-Server nicht). Im
Terminal geht es mit dem headersHelper von Claude Code einfacher: Claude
Code führt beim Verbinden einen Befehl aus und sendet dessen Ausgabe als
Header. Diese .mcp.json hat bei uns funktioniert:
Claude Code ruft den Helper beim Neuverbinden und nach einem 401 oder 403 erneut auf. Das einstündige Token wird so ohne Handarbeit erneuert.
Vier Punkte sollten Sie kennen, bevor Sie sich darauf verlassen:
- Jedes Abfrage-Tool erwartet eine
projectId, das Abrechnungsprojekt. Agenten übergeben gern das Projekt, dem die Daten gehören. Bei einem öffentlichen Dataset scheitert das mitUser does not have bigquery.jobs.create permission in project bigquery-public-data. In unserem ersten Durchlauf war "Run every query with projectId PROJECT_ID" nicht deutlich genug, "Always pass projectId PROJECT_ID to execute_sql_readonly; it is the billing project" dagegen schon. - Es gibt keinen Parameter
maximumBytesBilled. Eine einzelne Abfrage kann so viel lesen, wie die Identität lesen darf. Als Bremse bleibt ein benutzerdefiniertes Kontingent wieQueryUsagePerUserPerDay, das standardmäßig unbegrenzt ist. execute_sql_readonlylehnt alles außer SELECT ab (MCP execute_sql_readonly tool allows only SELECT statements.), der Agent kann aber weiterhinexecute_sqlaufrufen. Sperren Sie es mit einer IAM-Deny-Policy für schreibende MCP-Tools, wie unter Control MCP use with IAM beschrieben, oder mit einem Tool-Filter im Client.- Ergebnisse sind standardmäßig auf 3.000 Zeilen und Abfragen auf drei
Minuten begrenzt. Jeder Job trägt das Label
goog-mcp-server: true, so finden Sie Agenten-Abfragen inINFORMATION_SCHEMA.JOBS.
Option B: MCP Toolbox mit Schutzmechanismen
Die MCP Toolbox ist eine einzelne Go-Binärdatei. Version 1.16.0 erschien am 5. November 2026:
Unter macOS ersetzen Sie linux/amd64 durch darwin/arm64. Am schnellsten
starten Sie mit der vorgefertigten BigQuery-Konfiguration, die die
BigQuery-Dokumentation
für Claude Code, Cursor, VS Code und weitere Clients beschreibt. Sie bringt
neun Tools mit, darunter execute_sql, forecast, analyze_contribution
und ask_data_insights, und wird über Umgebungsvariablen wie
BIGQUERY_PROJECT, BIGQUERY_READONLY und BIGQUERY_MAXIMUM_BYTES_BILLED
konfiguriert.
Für einen Agenten, den Sie kontrollieren wollen, schreiben Sie eine eigene
tools.yaml. Diese Datei haben wir verwendet. Die Schutzmechanismen sitzen
an der Quelle, die Tools erben sie:
Was die Einstellungen bewirken:
readOnly: truelässtexecute_sqlnur SELECT ausführen. Die Toolbox prüft jede Abfrage vorher per Dry Run und lehnt andere Anweisungstypen ab.allowedDatasetslehnt Abfragen ab, die Tabellen außerhalb der Liste nennen, ebenso Anweisungen, die sie nicht analysieren kann, etwaCREATE FUNCTIONoderEXECUTE IMMEDIATE. Bei einem einzigen Dataset wird es außerdem zum Standard für die Auflistungs-Tools.maximumBytesBilledgeht mit jedem Job an BigQuery. Eine größere Abfrage scheitert, bevor sie abgerechnet wird.useClientOAuth: truelässt die Toolbox das Token des Clients verwenden. Ohne diese Option nutzt sie Application Default Credentials (ADC), die Sie mitgcloud auth application-default logineinrichten; das FeldimpersonateServiceAccountwechselt dann zum Dienstkonto.revenue_by_monthist eine feste, parametrisierte Abfrage. Der Agent liefert das Jahr, nie das SQL. Im Nur-Lese-Modus werden solche Tools ausgeblendet, außer sie tragen die AnnotationreadOnlyHint: true.kind: groupersetzt das älterekind: toolset. Die Gruppe bekommt einen eigenen Endpunkt, hier/mcp/analyst.
Server starten. Standardmäßig lauscht er auf 127.0.0.1:5000:
--config ersetzt das veraltete --tools-file, und Clients verbinden sich
per Streamable HTTP über /mcp (oder /mcp/analyst für die Gruppe). Der alte
SSE-Endpunkt /mcp/sse ist veraltet. Beim Start warnt die Toolbox, dass
--allowed-origins und --allowed-hosts standardmäßig * sind. Setzen Sie
beide, sobald der Server aus einem Browser oder aus dem Netz erreichbar ist.
Test mit MCP Inspector
MCP Inspector zeigt am schnellsten, was ein Agent zu sehen bekommt:
Version 2 startet mit einer Serverliste. Wählen Sie "Add Servers", "Add
manually", als Transport streamable-http und als URL
http://127.0.0.1:5000/mcp/analyst. Der Authorization-Header gehört in die
"Settings" des Servers unter "Custom Headers" (Secrets legt der Inspector im
Schlüsselbund des Betriebssystems ab). Nach dem Verbinden zeigt der Tab
"Tools" die vier Tools, jeweils als Nur-Lese-Tool markiert. In der
Beschreibung von execute_sql steht bereits die Allowlist, die Toolbox fügt
sie selbst ein:
MCP Inspector mit dem execute_sql-Tool der Toolbox, als Nur-Lese-Tool markiert, und einer Abfrage auf ein Dataset außerhalb der Allowlist
Die Abfrage oben liest ein anderes öffentliches Dataset, und die Toolbox lehnt sie ab, bevor BigQuery etwas ausführt:
MCP Inspector mit der Fehlermeldung der Toolbox: access to dataset bigquery-public-data.samples is not allowed
Das feste Tool revenue_by_month nimmt nur ein Jahr entgegen und liefert eine
Zeile pro Monat:
MCP Inspector mit Bestellungen und Umsatz pro Monat 2025 aus dem Tool revenue_by_month
Eine Abfrage über die 384 MB große Tabelle events stößt an die Grenze von
100 MB und wird nicht abgerechnet:
Einen Agenten anbinden
Für Claude Code funktioniert die headersHelper-Konfiguration aus Option A
auch mit der Toolbox, nur die URL lautet http://127.0.0.1:5000/mcp/analyst.
Wir haben Claude Code (Sonnet) nach den fünf umsatzstärksten
Produktkategorien 2025 gefragt und in drei Schritten die richtigen Zahlen
bekommen.
Für eine eigene Anwendung genügt ein kleiner Python-Agent mit dem OpenAI Agents SDK (0.24.0). Diese Version haben wir im Test verwendet:
Aufruf mit dem Token aus Schritt 1:
Für den Remote-Server setzen Sie MCP_URL auf https://bigquery.googleapis.com/mcp
und nennen das Abrechnungsprojekt in den Anweisungen ("Always pass projectId
PROJECT_ID to execute_sql_readonly").
Testergebnisse: sieben Geschäftsfragen
Wir haben dieselben sieben Fragen über beide Server gestellt, zuerst mit einem
knappen Prompt (der erste Absatz der Anweisungen oben plus "Revenue means the
sum of order_items.sale_price", beim Remote-Server zusätzlich "Run every query
with projectId PROJECT_ID"), dann mit den vollständigen Anweisungen, dem
deutlichen Satz zum Abrechnungsprojekt und dem Datumshinweis in der
Beschreibung von execute_sql. Die Referenzantworten stammen aus unserem
eigenen SQL. Die thelook-Daten werden regelmäßig neu erzeugt, an einem anderen
Tag sehen die Zahlen also anders aus.
| Frage | Referenzantwort | Toolbox, Lauf 1 → 2 | Remote-Server, Lauf 1 → 2 |
|---|---|---|---|
| Bestellungen 2025, Anteil storniert oder retourniert | 28.384, 24,9 % | richtig → richtig | falsches Abrechnungsprojekt, keine Antwort → richtig |
| Fünf umsatzstärkste Kategorien, abgeschlossene Bestellungen 2025 | Jeans, Outerwear & Coats, Sweaters, Suits & Sport Coats, Swim | von der Toolbox blockiert → richtig | richtig → richtig |
| Land mit den meisten Benutzern, deren Durchschnittsalter | China, 33.738 Benutzer, 40,93 Jahre | richtig → richtig | richtig → richtig |
| Durchschnittlicher Bestellwert, abgeschlossene Bestellungen Q4 2025 | 83,32 | richtig → richtig | richtig → richtig |
| Traffic-Quelle der meisten Benutzer mit Bestellung | Search, 56.031 | richtig → richtig | falsche Tabelle (Email) → richtig |
| Abteilung mit der höheren Bruttomarge 2025 | Women, 52,09 % zu 51,84 % | von der Toolbox blockiert → richtig | richtig → richtig |
| Browser mit den meisten Sitzungen | Chrome, 340.268 Sitzungen | 1.398.587 erfunden → Events statt Sitzungen | richtig → richtig |
Lauf 2 in Zahlen:
| Server | Richtig | Abfrage-Jobs | Verarbeitete Bytes | Abgerechnete Bytes | Input-Tokens |
|---|---|---|---|---|---|
| MCP Toolbox | 6 von 7 | 8 (1 von der Grenze gestoppt) | 44 MB | 114 MB | 27.564 |
| Remote-MCP-Server | 7 von 7 | 7 | 142 MB | 238 MB | 89.218 |
Der gesamte Test, beide Läufe und die Referenzabfragen, kostete in BigQuery
rund 1 GB abgerechnete Daten, also vernachlässigbar wenig. Der Remote-Server
verarbeitete mehr Bytes, weil er die Browser-Frage beantwortete, die 112 MB
liest. Er brauchte für dieselben Fragen außerdem dreimal so viele
Input-Tokens: Seine Tool-Beschreibungen sind lang, und get_table_info gibt
die vollständige Tabellenressource der BigQuery API zurück, die Toolbox nur
ein kompaktes Schema.
Stolpersteine aus dem Test
Die Allowlist der Toolbox lehnt EXTRACT(YEAR FROM o.created_at) ab. Mit
allowedDatasets liest Toolbox 1.16.0 Tabellennamen aus dem SQL-Text und hält
das FROM innerhalb von EXTRACT für eine Tabellenangabe. Die Abfrage
scheitert dann mit access to dataset 'pondhouse-docs.o' is not allowed,
wobei o der Tabellenalias ist. EXTRACT(YEAR FROM created_at) ohne Alias
funktioniert, Datumsvergleiche ebenso. Agenten schreiben aber ständig die
Variante mit Alias: Im ersten Lauf scheiterten daran zwei von sieben Fragen.
Ein Hinweis in der Tool-Beschreibung hat das behoben. Feste SQL-Tools
(bigquery-sql) sind nicht betroffen.
Nach einer blockierten Abfrage erfand der Agent eine Zahl. Die Browser-Frage lief zweimal in die Grenze von 100 MB. Danach antwortete der Agent "Chrome had the most sessions: 1,398,587", eine Zahl, die in keinem Abfrageergebnis vorkommt. Richtig sind 340.268. Mit der Regel "never estimate or make up numbers" zählte er stattdessen Events, was unter der Grenze bleibt, und sagte das auch. Das ist besser, beantwortet aber eine leicht andere Frage. Schutzmechanismen lassen Abfragen scheitern, und Ihr Agent braucht Anweisungen für genau diesen Fall.
Mehrdeutige Spalten führen zu plausiblen, falschen Antworten. Eine
Traffic-Quelle gibt es in users (wie der Kunde gewonnen wurde) und in
events (Quelle jedes Besuchs). Über den Remote-Server nahm der Agent
events und antwortete "Email" statt "Search". Das SQL war gültig, die
Antwort sah richtig aus. Eine Definition in einer Zeile der Anweisungen hat
das behoben. Bei Dutzenden Tabellen brauchen Sie solche Definitionen
systematisch. Unser Beitrag zu NVIDIA Auto
Ontology stellt ein Werkzeug vor,
das dafür eine semantische Schicht aufbaut.
Kleine Abfragen werden mit 10 MB abgerechnet. Eine Abfrage, die 1,3 MB der
Tabelle orders las, wurde mit 10 MB (10.485.760 Bytes) abgerechnet. Bei
vielen kleinen Agenten-Abfragen zählen die abgerechneten Bytes.
Die Toolbox ändert sich schnell. Zwischen Version 0.7 (Juni 2025) und 1.16
haben sich Konfigurationsformat, CLI-Optionen, Transport und toolset
geändert. Fixieren Sie die Version und lesen Sie vor einem Update die Release
Notes.
Checkliste für Sicherheit und Kosten
- Geben Sie dem Agenten ein eigenes Dienstkonto: BigQuery Job User auf dem
Abrechnungsprojekt, BigQuery Data Viewer nur auf den nötigen Datasets und
roles/mcp.toolUsernur, wenn Sie den Remote-Server nutzen. - Verwenden Sie kurzlebige Tokens per Impersonation oder Workload Identity statt Schlüsseldateien.
- Erlauben Sie nur Lesezugriff:
readOnly: truein der Toolbox, beim Remote-Server eine IAM-Deny-Policy für schreibende Tools. - Begrenzen Sie Kosten pro Abfrage mit
maximumBytesBilledin der Toolbox und pro Tag mit den benutzerdefinierten KontingentenQueryUsagePerDayundQueryUsagePerUserPerDay. - Bevorzugen Sie für produktive Agenten feste, parametrisierte Tools statt
freiem SQL. Laut Toolbox-Dokumentation ist
execute_sqlfür Entwickler-Workflows mit einem Menschen in der Schleife gedacht. - Machen Sie Abfragen nachvollziehbar: Beide Server versehen ihre Jobs mit
Labels (
goog-mcp-server: trueodermcp-toolbox-toolmit dem Tool-Typ), so filtern Sie Agenten-Abfragen samt abgerechneter Bytes inINFORMATION_SCHEMA.JOBS. Für den Remote-Server aktivieren Sie die Data Access Audit Logs für "Google Cloud MCP servers", sie sind standardmäßig aus. - Denken Sie daran, dass Abfrageergebnisse beim Modellanbieter landen. Halten Sie sensible Spalten mit Authorized Views oder Sicherheit auf Spaltenebene fern.
Welcher BigQuery-MCP-Server passt?
Beide Server lieferten richtige Antworten auf Geschäftsfragen, sobald der Agent klare Anweisungen hatte. Der Remote-Server ist schneller startklar und braucht keine eigene Infrastruktur. Sie steuern ihn vollständig über IAM, das ist sauber, aber die Kosten einer einzelnen Abfrage begrenzt er nicht. Die MCP Toolbox ist ein Prozess, den Sie betreiben. Dafür bietet sie die Kontrollen, die ein unbeaufsichtigter Agent haben sollte: Dataset-Allowlist, Nur-Lese-Modus, Byte-Grenze und feste SQL-Tools. Ihr Allowlist-Parser hat noch Schwächen, testen Sie ihn also mit dem SQL, das Ihr Agent tatsächlich schreibt.
In beiden Fällen hängt die Qualität weniger am Server als an den Anweisungen für den Agenten und an einem verständlichen Schema. Wenn Sie mit BigQuery weitergehen wollen, behandeln unsere Beiträge zur Vektorsuche in BigQuery (auf Englisch) und zum Vertex AI Agent Builder (auf Englisch) die benachbarten Bausteine.
Wir unterstützen Unternehmen in Österreich, Deutschland und der Schweiz dabei, KI-Agenten sicher an die eigenen Daten anzubinden, von der Einrichtung der Identitäten bis zur Bewertung der Antworten. Wenn Sie so einen Agenten planen, ist unsere KI-Beratung ein guter Ausgangspunkt.
Sie möchten zuverlässige KI-Agenten-Systeme bauen?
Wir haben auf Basis aktueller Forschung einen ausführlichen Leitfaden (auf Englisch) erstellt, wie Sie robuste KI-Agenten-Systeme bauen, die auch im produktiven Betrieb funktionieren. Der Leitfaden behandelt:
- die 14 systematischen Fehlerquellen in Multi-Agenten-Systemen
- belegte Best Practices für das Design von Agenten
- strukturierte Kommunikationsprotokolle und Prüfmechanismen



