metabase-mcp-mbql

Serveur MCP (Model Context Protocol) pour l'intégration avec Metabase, avec support complet de MBQL pour l'édition visuelle des requêtes.

Installation

npm install metabase-mcp-mbql

Configuration MCP

Ajoutez cette configuration à votre client MCP (Claude Desktop, etc.) :

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["metabase-mcp-mbql"],
      "env": {
        "METABASE_URL": "https://metabase.example.com",
        "METABASE_API_KEY": "mb_votre_cle_api"
      }
    }
  }
}

Authentification

Deux méthodes sont supportées :

1. Clé API (recommandé) :

{
  "METABASE_URL": "https://metabase.example.com",
  "METABASE_API_KEY": "mb_votre_cle_api"
}

2. Identifiants utilisateur :

{
  "METABASE_URL": "https://metabase.example.com",
  "METABASE_USERNAME": "votre_email",
  "METABASE_PASSWORD": "votre_mot_de_passe"
}

---

Outils disponibles

Dashboards

Outil	Description
list_dashboards	Liste tous les dashboards
get_dashboard	Récupère les détails complets d'un dashboard (cartes, paramètres)
create_dashboard	Crée un nouveau dashboard
update_dashboard	Met à jour un dashboard existant
delete_dashboard	Archive ou supprime un dashboard
get_dashboard_cards	Liste toutes les cartes d'un dashboard
add_card_to_dashboard	Ajoute une carte à un dashboard
remove_card_from_dashboard	Retire une carte d'un dashboard
update_dashboard_cards	Met à jour les cartes avec leurs mappings de paramètres
add_dashboard_filter	Ajoute ou met à jour un filtre sur un dashboard

Cards (Questions)

Outil	Description
list_cards	Liste toutes les questions/cartes (filtres: archived, table, database, using_model, bookmarked, using_segment, all, mine)
get_card	Récupère une carte avec sa configuration complète (dataset_query, template-tags)
create_card	Crée une nouvelle question
update_card	Met à jour une question existante
delete_card	Archive ou supprime une question
execute_card	Exécute une question et retourne les résultats

Requêtes MBQL

Outil	Description
create_card_mbql	Crée une question en MBQL (éditable dans le query builder visuel)
execute_mbql_query	Exécute une requête MBQL sans créer de carte

Requêtes SQL

Outil	Description
execute_query	Exécute une requête SQL native sur une base de données

Bases de données

Outil	Description
list_databases	Liste toutes les bases de données
get_database_metadata	Récupère les métadonnées complètes (tables, champs, IDs)
get_table_metadata	Récupère les métadonnées détaillées d'une table

Collections

Outil	Description
list_collections	Liste toutes les collections
create_collection	Crée une nouvelle collection
update_collection	Met à jour une collection

Utilisateurs

Outil	Description
list_users	Liste tous les utilisateurs
get_user	Récupère les détails d'un utilisateur
create_user	Crée un nouvel utilisateur
update_user	Met à jour un utilisateur
disable_user	Désactive un utilisateur

Permissions

Outil	Description
list_permission_groups	Liste les groupes de permissions
create_permission_group	Crée un groupe de permissions
delete_permission_group	Supprime un groupe de permissions
get_collection_permissions	Récupère le graphe des permissions par collection
update_collection_permissions	Met à jour les permissions d'un groupe sur une collection
add_user_to_group	Ajoute un utilisateur à un groupe
remove_user_from_group	Retire un utilisateur d'un groupe

---

Exemples d'utilisation

Créer une question MBQL

{
  "name": "Ventes par mois",
  "database_id": 1,
  "query": {
    "source-table": 123,
    "aggregation": [["sum", ["field", 456, null]]],
    "breakout": [["field", 789, {"temporal-unit": "month"}]]
  },
  "display": "line"
}

Configurer un filtre avec template-tag

{
  "card_id": 42,
  "dataset_query": {
    "type": "native",
    "database": 1,
    "native": {
      "query": "SELECT * FROM orders WHERE status = {{status}}",
      "template-tags": {
        "status": {
          "id": "abc-123",
          "name": "status",
          "display-name": "Statut",
          "type": "dimension",
          "dimension": ["field", 456, null],
          "widget-type": "category"
        }
      }
    }
  }
}

Connecter un filtre dashboard à une carte

{
  "dashboard_id": 10,
  "cards": [{
    "id": 100,
    "card_id": 42,
    "row": 0,
    "col": 0,
    "size_x": 6,
    "size_y": 4,
    "parameter_mappings": [{
      "parameter_id": "filter-1",
      "card_id": 42,
      "target": ["variable", ["template-tag", "status"]]
    }]
  }]
}

---

Développement

# Installation des dépendances
npm install

# Build
npm run build

# Watch mode
npm run watch

# Inspector MCP (debug)
npm run inspector

Licence

MIT