Metabase

Metabase MCP-Server

Metabase enthält einen integrierten Model Context Protocol (MCP)-Server, der es KI-Clients ermöglicht, sich direkt mit einer Metabase-Instanz zu verbinden. Er verwendet den https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http und baut auf der Agent-API von Metabase auf, um Werkzeuge zum Suchen, Navigieren, Abfragen, Visualisieren und Erstellen/Aktualisieren von Inhalten bereitzustellen – alles beschränkt auf die Berechtigungen des verbundenen Benutzers.

Endpunkt

Der MCP-Server ist verfügbar unter:

https://{your-metabase.example.com}/api/metabase-mcp

Der veraltete Pfad /api/mcp funktioniert weiterhin als Alias für bestehende Clients, aber /api/metabase-mcp ist die kanonische URL, die angegeben werden sollte.

Verbinden eines Clients

Richten Sie einen beliebigen MCP-kompatiblen Client auf den Endpunkt /api/metabase-mcp aus. Zum Beispiel mit Claude Code:

claude mcp add metabase https://{your-metabase.example.com}/api/metabase-mcp --transport streamable-http

Erstellen Sie für Claude Desktop einen benutzerdefinierten Connector mit derselben URL.

Öffnen Sie für Cursor Einstellungen > MCP und fügen Sie einen neuen Server hinzu, wobei Sie den Typ auf streamable-http und die URL auf Folgendes setzen:

https://{your-metabase.example.com}/api/metabase-mcp

Authentifizierung

MCP-Clients authentifizieren sich über OAuth 2.0. Metabase betreibt einen eigenen eingebetteten OAuth-Server – es wird kein externer Anbieter benötigt.

Der Ablauf für eine erstmalige Verbindung:

1. Der Client entdeckt die OAuth-Endpunkte von Metabase.
2. Der Client registriert sich selbst bei Metabase.
3. Der Benutzer wird zu Metabase weitergeleitet, um sich anzumelden und die Verbindung zu genehmigen.
4. Der Client erhält ein Zugriffstoken, das auf die Metabase-Berechtigungen des Benutzers beschränkt ist.

Browserbasierte Sitzungen (Cookie-Authentifizierung) werden ebenfalls unterstützt und erhalten uneingeschränkte Bereiche.

Bereiche

Zugriffstoken sind auf bestimmte Bereiche beschränkt, um einzuschränken, welche Werkzeuge ein Client verwenden kann:

Bereich	Gewährt Zugriff auf
agent:search	search
agent:resource:read	read_resource (wird jedem authentifizierten Aufrufer immer gewährt; Berechtigungsprüfungen pro URI finden im Dispatcher statt)
agent:query:construct	construct_query
agent:query	query
agent:query:execute	execute_query
agent:sql:construct	construct_native_query
agent:sql:execute	execute_sql
agent:question:create	create_question
agent:question:update	update_question (umfasst auch „Karte in Sammlung verschieben“ und Archivierung)
agent:question:execute	execute_question
agent:metric:create	create_metric
agent:metric:update	update_metric (umfasst auch „Metrik in Sammlung verschieben“ und Archivierung)
agent:dashboard:create	create_dashboard
agent:dashboard:update	update_dashboard (umfasst auch Archivierung)
agent:collection:create	create_collection

Wildcard-Muster (z. B. agent:*) stimmen mit jedem Bereich überein, der dieses Präfix hat.

Metadaten zu geschützten OAuth-Ressourcen sind verfügbar unter:

/.well-known/oauth-protected-resource/api/metabase-mcp

Standardmäßig gewährt unser Zustimmungsbildschirm Zugriff auf alle Bereiche, ohne die Möglichkeit zur Anpassung.

Verfügbare Werkzeuge

Der MCP-Server stellt die folgenden Werkzeuge bereit, die dynamisch aus den Metadaten der Agent-API-Endpunkte generiert werden:

Erkennung + Lesen

Werkzeug	Beschreibung
search	Suche nach Tabellen, Metriken, Karten, Dashboards und Sammlungen mit Schlüsselwort- oder natürlichsprachlichen Abfragen.
read_resource	Lesen einer oder mehrerer Metabase-Entitäten anhand der metabase://-URI. Deckt die Navigation in Datenbank/Schema/Tabelle/Sammlung/Frage/Dashboard/Metrik/Transformation ab. Bis zu 5 URIs pro Aufruf.

Abfrageerstellung + -ausführung

Werkzeug	Beschreibung
construct_query	Erstellt eine Abfrage für eine Tabelle oder Metrik. Akzeptiert die ursprüngliche prompt des Benutzers, falls verfügbar. Gibt ein undurchsichtiges query_handle zur Verwendung mit execute_query oder visualize_query zurück.
construct_native_query	Erstellt eine native (reines SQL) Abfrage für eine Datenbank. Gibt ein undurchsichtiges query_handle zurück, um create_question zu füttern und zu speichern. Führt das SQL nicht aus; native Handles werden von execute_query/query abgelehnt (verwenden Sie execute_sql, um reines SQL auszuführen).
query	Fragt eine Tabelle oder Metrik direkt ab. Unterstützt Paginierung über Fortsetzungstoken.
execute_query	Führt eine zuvor erstellte Abfrage aus und gibt Ergebnisse mit Spaltenmetadaten zurück.
execute_sql	Führt eine reine SQL-Abfrage für eine Datenbank aus. Erfordert, dass der Benutzer die Berechtigung für native Abfragen auf der Zieldatenbank hat. Kann instanzweit über die Einstellung mcp-execute-sql-enabled deaktiviert werden.
execute_question	Führt eine gespeicherte Frage anhand der ID aus und gibt ihre Zeilen + Spaltenmetadaten zurück. Wird unter den Berechtigungen des Aufrufers ausgeführt. Parametrisierte Fragen werden nicht unterstützt (gibt einen Fehler zurück).

Schreiben

Werkzeug	Beschreibung
create_metric	Speichert eine Abfrage als wiederverwendbare Metrik. Akzeptiert ein query_handle von construct_query. Die Abfrage benötigt eine Aggregation und höchstens eine Datumsgruppierung.
update_metric	Aktualisiert eine gespeicherte Metrik. Patch-Semantik. Das Setzen von collection_id verschiebt sie; das Setzen von archived: true archiviert sie – ein reversibles Soft-Delete, das verwendet wird, wenn das Löschen einer Metrik angefordert wird. Ein Ersatz-query muss weiterhin eine gültige Metrik sein.
create_question	Speichert eine Abfrage als benannte Frage (Karte). Akzeptiert ein query_handle von construct_query (MBQL) oder construct_native_query (natives SQL). Das Speichern nativer Abfragen erfordert die DB-Berechtigung für native Abfragen.
update_question	Aktualisiert eine gespeicherte Frage. Patch-Semantik. Das Setzen von collection_id verschiebt die Karte. Das Setzen von archived: true archiviert sie – ein reversibles Soft-Delete, das verwendet wird, wenn das Löschen einer Frage angefordert wird. Das Ersetzen der Abfrage akzeptiert ein construct_query- oder construct_native_query-Handle.
create_dashboard	Erstellt ein neues Dashboard, optional bestückt mit gespeicherten Fragen (automatisch im Raster positioniert).
update_dashboard	Aktualisiert die Metadaten eines Dashboards (Name, Beschreibung, Sammlung, archiviert – ein reversibles Soft-Delete, das verwendet wird, wenn das Löschen eines Dashboards angefordert wird).
create_collection	Erstellt eine neue Sammlung. Optional verschachtelt unter einer parent_collection_id.

Abfrageergebnisse sind auf 200 Zeilen pro Anfrage begrenzt. Wenn mehr Zeilen verfügbar sind, enthält die Antwort ein continuation_token, das zurückgegeben werden kann, um die nächste Seite abzurufen.

read_resource-Listenantworten sind auf 25 Elemente mit truncated / total-Signalen begrenzt; gehen Sie tiefer in bestimmte URIs, um mehr zu sehen, oder verfeinern Sie die Ergebnisse über search.

Ressourcen

Der Server stellt MCP-Ressourcen bereit, damit Clients ergänzende Inhalte per URI abrufen können, ohne die Werkzeugbeschreibungen aufzublähen.

Ressourcen-URI	Beschreibung
metabase://docs/construct-query.md	Programmsyntax für construct_query und query: Quellen, Operationen, Operatorformen, Arbeitsbeispiele, Fallstricke.

Das read_resource-Werkzeug (oben) verwendet ein separates URI-Schema, um Metabase-Entitäten zu navigieren (metabase://question/{id}, metabase://database/{id}/tables usw.). Die beiden URI-Namensräume sind unabhängig: metabase://docs/... ist für statische Referenzinhalte, die über MCP resources/read abgerufen werden, während metabase://table/... und ähnliche Entitäts-URIs sind, die an das read_resource-Werkzeug übergeben werden.

Unterstützte JSON-RPC-Methoden

Methode	Beschreibung
initialize	Initialisiert die MCP-Verbindung. Gibt Serverfähigkeiten und eine Sitzungs-ID zurück.
notifications/initialized	Client-Benachrichtigung, dass die Initialisierung abgeschlossen ist.
tools/list	Listet verfügbare Werkzeuge auf (gefiltert nach den Bereichen des Tokens).
tools/call	Ruft ein Werkzeug mit Argumenten auf.
resources/list	Listet verfügbare Ressourcen auf (gefiltert nach den Bereichen des Tokens).
resources/read	Liest eine Ressource anhand der URI. Erfordert eine initialisierte Sitzung.
ping	Keepalive-Ping.

Anfragen können einzeln oder als JSON-RPC-Stapel gesendet werden. Der Server antwortet je nach Accept-Header mit JSON oder SSE.

Architektur

Die Implementierung befindet sich in diesen Dateien:

• api.clj - Der HTTP-Handler. Parst JSON-RPC-Anfragen, validiert Authentifizierungs- und Sitzungsheader, erzwingt Ursprungsprüfungen (DNS-Rebinding-Schutz) und leitet an die entsprechende Methode weiter. Unterstützt sowohl JSON- als auch SSE-Antwortformate.

• tools.clj - Werkzeug-Dispatch und Manifest-Generierung. Erstellt die Werkzeugliste aus den Metadaten der Agent-API-Endpunkte, prüft Bereiche und leitet Werkzeugaufrufe über synthetische Agent-API-Anfragen weiter.

• resources.clj - MCP-Ressourcen-Registry und -Handler. Enthält Dokumentationsressourcen (wie die construct_query-Referenz), die nach URI verschlüsselt sind, mit bereichsbasierter Zugriffskontrolle für resources/list und resources/read.

• scope.clj – Bereichsabgleichslogik. Unterstützt exakte Übereinstimmungen, Platzhaltermuster und den ::unrestricted-Sentinel für sitzungsbasierte Authentifizierung.

Anfrageablauf

MCP client
  -> POST /api/metabase-mcp (JSON-RPC)
  -> Origin + session validation
  -> Auth: OAuth bearer token or browser session
  -> Scope check against requested tool
  -> Synthetic request to Agent API endpoint
  -> Response materialized as MCP content
  -> JSON or SSE back to client

Weiterführende Informationen

• MCP-Benutzerdokumentation
• Agent-API-Quelle
• Model Context Protocol-Spezifikation