Metabase

Serveur MCP Metabase

Metabase inclut un serveur Model Context Protocol (MCP) intégré qui permet aux clients IA de se connecter directement à une instance Metabase. Il utilise le https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http et s'appuie sur l'API Agent de Metabase pour exposer des outils de recherche, navigation, interrogation, visualisation et création/mise à jour de contenu, le tout limité aux autorisations de l'utilisateur connecté.

Point de terminaison

Le serveur MCP est disponible à l'adresse :

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

L'ancien chemin /api/mcp fonctionne toujours comme alias pour les clients existants, mais /api/metabase-mcp est l'URL canonique à annoncer.

Connexion d'un client

Pointez n'importe quel client compatible MCP vers le point de terminaison /api/metabase-mcp. Par exemple, avec Claude Code :

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

Pour Claude Desktop, créez un connecteur personnalisé en utilisant la même URL.

Pour Cursor, ouvrez Paramètres > MCP et ajoutez un nouveau serveur avec le type défini sur streamable-http et l'URL :

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

Authentification

Les clients MCP s'authentifient via OAuth 2.0. Metabase exécute son propre serveur OAuth intégré - aucun fournisseur externe n'est nécessaire.

Le flux pour une première connexion :

1. Le client découvre les points de terminaison OAuth de Metabase.
2. Le client s'enregistre auprès de Metabase.
3. L'utilisateur est redirigé vers Metabase pour se connecter et approuver la connexion.
4. Le client reçoit un jeton d'accès limité aux autorisations Metabase de l'utilisateur.

Les sessions basées sur navigateur (authentification par cookie) sont également prises en charge et reçoivent des portées illimitées.

Portées

Les jetons d'accès sont limités pour restreindre les outils qu'un client peut utiliser :

Portée	Accorde l'accès à
agent:search	search
agent:resource:read	read_resource (toujours accordé à tout appelant authentifié ; les vérifications de permissions par URI ont lieu à l'intérieur du répartiteur)
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 (couvre également "déplacer la carte vers la collection" et l'archivage)
agent:question:execute	execute_question
agent:metric:create	create_metric
agent:metric:update	update_metric (couvre également "déplacer la métrique vers la collection" et l'archivage)
agent:dashboard:create	create_dashboard
agent:dashboard:update	update_dashboard (couvre également l'archivage)
agent:collection:create	create_collection

Les motifs génériques (par ex. agent:*) correspondent à toute portée avec ce préfixe.

Les métadonnées de ressource protégée OAuth sont disponibles à l'adresse :

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

Par défaut, notre écran de consentement accorde l'accès à toutes les portées sans possibilité de personnalisation.

Outils disponibles

Le serveur MCP expose ces outils, générés dynamiquement à partir des métadonnées du point de terminaison de l'API Agent :

Découverte + lecture

Outil	Description
search	Rechercher des tables, métriques, cartes, tableaux de bord et collections à l'aide de mots-clés ou de requêtes en langage naturel.
read_resource	Lire une ou plusieurs entités Metabase par URI metabase://. Couvre la navigation base de données/schéma/table/collection/question/tableau de bord/métrique/transformation. Jusqu'à 5 URI par appel.

Construction + exécution de requêtes

Outil	Description
construct_query	Construire une requête sur une table ou une métrique. Accepte le prompt original de l'utilisateur lorsqu'il est disponible. Retourne un query_handle opaque à utiliser avec execute_query ou visualize_query.
construct_native_query	Construire une requête native (SQL brut) pour une base de données. Retourne un query_handle opaque à fournir à create_question et à sauvegarder. N'exécute pas le SQL ; les handles natifs sont rejetés par execute_query/query (utilisez execute_sql pour exécuter du SQL brut).
query	Interroger directement une table ou une métrique. Prend en charge la pagination via des jetons de continuation.
execute_query	Exécuter une requête précédemment construite et retourner les résultats avec les métadonnées des colonnes.
execute_sql	Exécuter une requête SQL brute sur une base de données. Nécessite que l'utilisateur ait la permission de requête native sur la base de données cible. Peut être désactivé pour toute l'instance via le paramètre mcp-execute-sql-enabled.
execute_question	Exécuter une question sauvegardée par son id et retourner ses lignes + métadonnées de colonnes. S'exécute sous les permissions de l'appelant. Les questions paramétrées ne sont pas prises en charge (retourne une erreur).

Écriture

Outil	Description
create_metric	Sauvegarder une requête en tant que métrique réutilisable. Accepte un query_handle de construct_query. La requête nécessite une agrégation et au plus un regroupement par date.
update_metric	Mettre à jour une métrique sauvegardée. Sémantique de correction. Définir collection_id la déplace ; définir archived: true l'archive — une suppression logique réversible, utilisée lorsqu'il est demandé de supprimer une métrique. Un query de remplacement doit toujours être une métrique valide.
create_question	Sauvegarder une requête en tant que question nommée (carte). Accepte un query_handle de construct_query (MBQL) ou construct_native_query (SQL natif). La sauvegarde native nécessite la permission DB de requête native.
update_question	Mettre à jour une question sauvegardée. Sémantique de correction. Définir collection_id déplace la carte. Définir archived: true l'archive — une suppression logique réversible, utilisée lorsqu'il est demandé de supprimer une question. Le remplacement de la requête accepte un handle construct_query ou construct_native_query.
create_dashboard	Créer un nouveau tableau de bord, éventuellement peuplé de questions sauvegardées (positionnées automatiquement sur la grille).
update_dashboard	Mettre à jour les métadonnées d'un tableau de bord (nom, description, collection, archivé — une suppression logique réversible, utilisée lorsqu'il est demandé de supprimer un tableau de bord).
create_collection	Créer une nouvelle collection. Éventuellement imbriquée sous un parent_collection_id.

Les résultats de requête sont limités à 200 lignes par requête. Lorsque plus de lignes sont disponibles, la réponse inclut un continuation_token qui peut être renvoyé pour récupérer la page suivante.

Les réponses de liste read_resource sont limitées à 25 éléments avec des signaux truncated / total ; explorez des URI spécifiques pour en voir plus, ou affinez via search.

Ressources

Le serveur expose les ressources MCP afin que les clients puissent récupérer du contenu supplémentaire par URI sans alourdir les descriptions d'outils.

URI de ressource	Description
metabase://docs/construct-query.md	Syntaxe du programme pour construct_query et query : sources, opérations, formes d'opérateur, exemples concrets, pièges.

L'outil read_resource (ci-dessus) utilise un schéma d'URI distinct pour naviguer dans les entités Metabase (metabase://question/{id}, metabase://database/{id}/tables, etc.). Les deux espaces de noms d'URI sont indépendants : metabase://docs/... est pour le contenu de référence statique récupéré via MCP resources/read, tandis que metabase://table/... et similaires sont des URI d'entité passés à l'outil read_resource.

Méthodes JSON-RPC prises en charge

Méthode	Description
initialize	Initialiser la connexion MCP. Retourne les capacités du serveur et un ID de session.
notifications/initialized	Notification du client indiquant que l'initialisation est terminée.
tools/list	Lister les outils disponibles (filtrés par les portées du jeton).
tools/call	Appeler un outil avec des arguments.
resources/list	Lister les ressources disponibles (filtrées par les portées du jeton).
resources/read	Lire une ressource par URI. Nécessite une session initialisée.
ping	Ping de maintien de connexion.

Les requêtes peuvent être envoyées individuellement ou par lot JSON-RPC. Le serveur répond avec JSON ou SSE selon l'en-tête Accept.

Architecture

L'implémentation réside dans ces fichiers :

• api.clj - Le gestionnaire HTTP. Analyse les requêtes JSON-RPC, valide les en-têtes d'authentification et de session, applique les vérifications d'origine (protection contre le rebinding DNS) et distribue vers la méthode appropriée. Prend en charge les formats de réponse JSON et SSE.

• tools.clj - Distribution des outils et génération du manifeste. Construit la liste d'outils à partir des métadonnées du point de terminaison de l'API Agent, vérifie les portées et route les appels d'outils via des requêtes synthétiques de l'API Agent.

• resources.clj - Registre de ressources MCP et gestionnaires. Contient les ressources de documentation (comme la référence construct_query) indexées par URI, avec contrôle d'accès basé sur les portées sur resources/list et resources/read.

• scope.clj - Logique de correspondance de portée. Prend en charge les correspondances exactes, les motifs génériques et le marqueur ::unrestricted pour l'authentification basée sur la session.

Flux de la requête

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

Pour aller plus loin

• Documentation utilisateur MCP
• Source de l'API Agent
• Spécification du protocole Model Context