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