# 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
```bash
npm install metabase-mcp-mbql
```
## Configuration MCP
Ajoutez cette configuration à votre client MCP (Claude Desktop, etc.) :
```json
{
"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é) :**
```json
{
"METABASE_URL": "https://metabase.example.com",
"METABASE_API_KEY": "mb_votre_cle_api"
}
```
**2. Identifiants utilisateur :**
```json
{
"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
```json
{
"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
```json
{
"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
```json
{
"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
```bash
# Installation des dépendances
npm install
# Build
npm run build
# Watch mode
npm run watch
# Inspector MCP (debug)
npm run inspector
```
## Licence
MIT
