Aller au contenu principal

emMCP — Serveur MCP pour Dolibarr

emMCP installe un serveur MCP (Model Context Protocol) directement dans Dolibarr. Un client compatible — Claude.ai, Claude Code ou un client MCP HTTP personnalisé — peut alors interroger et manipuler vos données Dolibarr (tiers, factures, produits, stocks, environnement…) en langage naturel.

Le principe central : pour les outils métier standards, emMCP n'introduit aucun droit nouveau. Chaque appel s'authentifie comme un utilisateur Dolibarr réel (clé API ou OAuth 2.1) et passe par l'API REST de Dolibarr, qui applique les droits existants de cet utilisateur. Seul l'outil de requête SQL fait exception : c'est un droit Dolibarr dédié, distinct, qui n'existe pas dans un Dolibarr standard (voir la section dédiée plus bas).

Confidentialité : emMCP tourne sur votre serveur, mais son rôle est de transmettre les données demandées au client IA connecté (claude.ai, Claude Code, ou un autre). Ces données quittent donc Dolibarr vers le fournisseur IA choisi, selon les conditions de ce fournisseur — héberger le module chez vous ne garantit pas que les données restent exclusivement dans Dolibarr, c'est le principe même du protocole MCP.

Page de configuration emMCP avec l'URL du connecteur, la commande Claude Code et le fichier mcp.json

Prérequis

Élément Version minimum
Dolibarr Version récente
PHP PHP ≥ 8.1
Module API REST Dolibarr Actif (requis)
Connexion HTTPS obligatoire
Base de données MySQL ou MariaDB pour l'outil SQL (voir plus bas)

emMCP est un module autonome : il embarque ses propres dépendances (serveur MCP, gestion OAuth, moteur SQL). Aucune installation préalable d'un autre module E-dem n'est nécessaire.

Note : le module API REST natif de Dolibarr doit être activé — emMCP l'utilise pour exécuter les actions avec les permissions de l'utilisateur authentifié.

Installation

Depuis le DoliStore

  1. Rendez-vous sur le DoliStore et recherchez emMCP
  2. Achetez le module et téléchargez l'archive ZIP
  3. Décompressez l'archive dans le dossier htdocs/custom/ de votre installation Dolibarr
  4. Le dossier final doit être htdocs/custom/emmcp/

Activation

  1. Connectez-vous à Dolibarr en tant qu'administrateur
  2. Allez dans Accueil → Configuration → Modules/Applications
  3. Recherchez « emMCP » et cliquez sur Activer
  4. Assurez-vous que le module API REST de Dolibarr est également actif

Un nouveau menu de configuration emMCP apparaît, avec quatre onglets : Paramètres, Accès SQL MCP, Activité MCP, À propos.

Mettre à jour le module

Sauvegardez la base de données Dolibarr et le dossier actuel du module avant de remplacer les fichiers ; testez la mise à jour sur une instance hors production si possible.

  1. Téléchargez la nouvelle version depuis le DoliStore
  2. Remplacez les fichiers dans htdocs/custom/emmcp/ (ou décompressez par-dessus l'installation existante)
  3. Retournez sur la page de configuration emMCP et vérifiez les onglets SQL et Activité pour appliquer les éventuelles mises à jour de leurs tables
  4. Vos réglages (SQL, journalisation, quota, alertes) et vos utilisateurs autorisés sont conservés

Reconnecter un client après changement d'URL ou de clé

Si vous changez de domaine, régénérez une clé API, ou recréez un connecteur claude.ai :

  • Claude.ai : supprimez l'ancien connecteur personnalisé et recréez-le avec la nouvelle URL — le consentement OAuth est à redonner
  • Claude Code : supprimez l'ancienne entrée avec claude mcp remove dolibarr, puis relancez la commande claude mcp add ci-dessous avec la nouvelle URL et/ou clé API, dans le même périmètre de configuration qu'auparavant
  • Client générique : mettez à jour url et/ou headers.Authorization dans votre mcp.json

Connecter un client

L'onglet Paramètres affiche l'URL de votre serveur MCP et génère, pour chaque type de client, la commande ou le fichier prêt à copier.

Claude.ai (connecteur personnalisé — recommandé)

  1. Dans claude.ai : Paramètres → Connecteurs → « Ajouter un connecteur personnalisé »
  2. Collez l'URL du connecteur affichée dans la page de configuration emMCP (https://votre-dolibarr/custom/emmcp/mcp.php)
  3. Claude découvre automatiquement l'authentification OAuth 2.1, vous redirige vers votre Dolibarr pour vous connecter, et vous demande votre consentement — aucune clé à copier

Claude Code

Authentification par clé API Dolibarr, en en-tête Authorization: Bearer (recommandé) ou DOLAPIKEY.

claude mcp add dolibarr --transport http https://votre-dolibarr/custom/emmcp/mcp.php \
  --header "Authorization: Bearer VOTRE_CLE_API"

Client MCP générique (mcp.json)

Pour tout client MCP supportant le transport HTTP :

{
    "mcpServers": {
        "dolibarr": {
            "type": "http",
            "url": "https://votre-dolibarr/custom/emmcp/mcp.php",
            "headers": {
                "Authorization": "Bearer VOTRE_CLE_API"
            }
        }
    }
}

Obtenir une clé API

La clé API d'un utilisateur se génère depuis sa fiche : Utilisateurs & Groupes → fiche utilisateur → onglet « Clé pour API ». L'utilisateur doit avoir les permissions Dolibarr adaptées aux actions attendues de l'agent, puisque l'agent agit avec ses droits.

Remplacez VOTRE_CLE_API par la clé réelle générée pour l'utilisateur concerné. Ne partagez jamais cette clé et ne la publiez jamais dans un dépôt de code.

Permissions et authentification

emMCP ne crée aucun compte technique séparé. Il s'appuie entièrement sur l'authentification et les droits Dolibarr existants.

Méthodes d'authentification

Méthode Usage
Clé API Dolibarr (Authorization: Bearer ou DOLAPIKEY) Claude Code, clients MCP génériques, scripts
OAuth 2.1 avec PKCE obligatoire (S256) Claude.ai et connecteurs équivalents

L'implémentation OAuth est conforme aux RFC 9728 (Protected Resource Metadata), 8414 (Authorization Server Metadata) et 7591 (Dynamic Client Registration). Les jetons d'accès sont courts (1 heure), les jetons de rafraîchissement (30 jours) sont automatiquement remplacés à chaque rafraîchissement (rotation), et tous les jetons sont stockés uniquement sous forme de hachage — jamais en clair.

Permissions effectives

Il n'existe aucun rôle « agent IA » dans Dolibarr : chaque outil métier standard s'exécute avec exactement les droits de l'utilisateur Dolibarr authentifié, via l'API REST native. Ces outils apparaissent dans la liste proposée à l'agent quel que soit votre droit réel sur l'objet visé — c'est Dolibarr, via l'API REST, qui refuse l'exécution si le droit manque (l'outil est visible, l'action est refusée). Seul l'outil de requête SQL est structurellement masqué tant que ses quatre conditions ne sont pas réunies (voir plus bas) : c'est la seule vraie différence entre « outil invisible » et « outil visible mais refusé à l'exécution ».

Pour réduire la surface d'action d'un agent, la meilleure pratique reste de lui dédier un utilisateur Dolibarr à droits restreints (principe du moindre privilège), en s'appuyant sur les permissions Dolibarr fines par objet (lecture seule sur certains modules, pas de droit de suppression, etc.) plutôt que de connecter un compte administrateur.

Révoquer un accès

Il n'existe pas de droit générique « accès emMCP » à retirer : les outils métier standards suivent simplement les droits Dolibarr habituels de l'utilisateur. La révocation dépend donc du mode de connexion :

  • Client par clé API (Claude Code, client générique) : régénérez la clé API de l'utilisateur Dolibarr concerné (fiche utilisateur → onglet « Clé pour API »). Cela coupe immédiatement l'accès de ce client.
  • Connecteur OAuth (claude.ai) : régénérer la clé API ne suffit pas — le jeton d'accès OAuth (1 heure) se renouvelle automatiquement via son jeton de rafraîchissement, indépendamment de la clé API ; l'expiration n'équivaut pas à une révocation. Pour couper l'accès immédiatement, désactivez l'utilisateur Dolibarr associé ou désactivez le module emMCP.

Il n'y a pas de bouton self-service pour révoquer un jeton OAuth précis dans cette version. Pour un besoin de révocation ciblée au-delà de ce que permet la désactivation d'un utilisateur ou du module, contactez le support E-dem.

Droit dédié SQL : le droit « Accès SQL MCP » (emmcp->sqlquery->read), lui, est un vrai droit Dolibarr qui se retire normalement depuis la fiche utilisateur, en plus de son opt-in — voir la section SQL ci-dessous.

Outils disponibles

emMCP expose un ensemble d'outils MCP qui couvrent la majorité de l'API REST de Dolibarr. Ils apparaissent tous dans la liste proposée à l'agent ; c'est l'API REST de Dolibarr qui refuse l'exécution si le droit de l'utilisateur manque.

Famille Outils Rôle
Lecture dolibarr_list, dolibarr_get, dolibarr_get_contacts Lister, récupérer un enregistrement, lister les contacts liés
Écriture dolibarr_create, dolibarr_create_from, dolibarr_update, dolibarr_delete Créer, créer à partir d'un autre objet (ex. devis → facture), modifier, supprimer
Lignes & temps dolibarr_add_line, dolibarr_add_time_spent Ajouter une ligne à un document, saisir du temps passé
Workflow dolibarr_action Déclencher une action métier (ex. valider un document)
Contacts dolibarr_link_contact Lier un contact à un objet
Champs complémentaires dolibarr_extrafield_update, dolibarr_extrafield_delete Gérer les extrafields d'un objet
Documents dolibarr_documents_list, dolibarr_documents_upload, dolibarr_documents_download, dolibarr_documents_delete, dolibarr_documents_builddoc Gérer les fichiers attachés et générer un document (ex. PDF)
Fichiers dolibarr_files_create Créer un fichier générique
Diagnostic dolibarr_environment, dolibarr_api_explorer Informations sur l'instance connectée ; explorer les endpoints REST disponibles
SQL dolibarr_sql_query, dolibarr_sql_schema Requête et schéma SQL en lecture seule — masqués tant que les 4 conditions ne sont pas réunies, voir ci-dessous

Exemple : workflow prudent avant une action qui modifie des données

Les outils d'écriture (dolibarr_create, dolibarr_update, dolibarr_delete, dolibarr_action pour une validation…) agissent réellement sur votre Dolibarr. Bonne pratique recommandée pour ces cas :

  1. Demandez d'abord à l'agent de lister ou récupérer l'enregistrement concerné (dolibarr_list / dolibarr_get) et d'afficher ce qu'il compte modifier
  2. Validez vous-même que c'est bien l'enregistrement attendu
  3. Demandez explicitement l'action d'écriture, plutôt que de lui laisser un mandat large et implicite (« occupe-toi de mes factures »)

Ceci relève de l'usage du client IA (Claude.ai, Claude Code) plutôt que d'un réglage emMCP : le module applique les droits Dolibarr, mais ne peut pas savoir si une demande formulée en langage naturel est ambiguë.

Accès SQL en lecture seule

Au-delà des outils métier standards, emMCP peut exposer un outil de requête SQL en lecture seule. Ce n'est pas un droit métier Dolibarr ordinaire : accorder cet accès donne une lecture large de la base de données, bien au-delà des permissions métier habituelles (marges, salaires, tous les tiers sans restriction commerciale). Dolibarr affiche lui-même cet avertissement dans la page de configuration.

Page de configuration de l'accès SQL MCP avec activation globale, plafonds, utilisateurs autorisés et périmètre refusé

Les quatre conditions

L'outil SQL reste invisible pour l'agent tant que les quatre conditions suivantes ne sont pas toutes réunies :

  1. Interrupteur global activé dans la configuration du module (désactivé par défaut)
  2. Droit Dolibarr dédié accordé à l'utilisateur (« Accès SQL MCP », onglet Permissions de sa fiche)
  3. Opt-in individuel coché nominativement pour l'utilisateur dans la page de configuration — le droit seul ne suffit pas
  4. Absence de blocage Multicompany : en environnement multi-société, l'accès est refusé par défaut (une requête SQL brute ne peut pas être filtrée de façon fiable par entité), sauf activation explicite du support multi-entité

Ce qui protège la requête elle-même

  • Une seule instruction SELECT ou WITH par appel, sur la connexion Dolibarr existante — aucun compte MySQL séparé n'est requis ni créé. Les requêtes utilisent les identifiants Dolibarr eux-mêmes, sur une session mysqli distincte.
  • Chaque requête est analysée par un lexeur et un analyseur syntaxique qui refusent toute requête qui n'est pas structurellement un SELECT (un mot comme « UPDATE » présent dans une valeur texte recherchée reste autorisé : ce n'est pas une écriture, seule la structure de la requête compte).
  • Plafonds par défaut : 200 lignes (maximum configurable 5000) et 256 Kio de taille de réponse (maximum 4 Mio), appliqués par le module lui-même en lisant les résultats en flux, sans les charger entièrement en mémoire ; 5 secondes de délai maximum (maximum 30) et transaction en lecture seule, eux appliqués par la session MySQL/MariaDB elle-même.
  • Colonnes sensibles refusées nommément : mots de passe, clés API, jetons, secrets (pass, pass_crypted, api_key, token, client_secret, refresh_token, secret, private_key…), ainsi que tout nom de colonne contenant un fragment sensible (password, token, secret, credential…).
  • SELECT * n'est pas interdit en bloc : il est résolu colonne par colonne, et refusé nommément seulement s'il exposerait une colonne sensible.
  • Fonctions à risque bloquées : sleep, benchmark, get_lock, release_lock, load_file, sys_exec, sys_eval, etc.
  • Tables techniques exclues : tables de session, de jetons OAuth, d'audit et de permissions des modules emMCP (et, le cas échéant, d'autres modules E-dem partageant la base) sont explicitement hors périmètre.
  • Chaque requête est journalisée avec ses métadonnées (utilisateur, durée, nombre de lignes, statut) ; les résultats ne sont jamais enregistrés. Le texte de la requête peut lui-même être réduit à une empreinte SHA-256 si votre politique de confidentialité l'exige (case « Ne journaliser que l'empreinte des requêtes »).

Exemple de requête acceptée

SELECT rowid, ref, total_ttc, datef
FROM llx_facture
WHERE fk_statut = 1
ORDER BY datef DESC
LIMIT 20

Une requête nommant explicitement ses colonnes comme ci-dessus est plus lisible à auditer dans le journal qu'un SELECT *, même si ce dernier reste autorisé quand aucune colonne sensible n'est exposée.

Limites honnêtes

⚠️ Cet outil est réservé à MySQL/MariaDB — PostgreSQL n'est pas supporté pour l'outil SQL. C'est un garde-fou de volume et de périmètre, pas une garantie absolue contre tout risque : gardez-le désactivé si vous n'en avez pas l'usage, et n'accordez le droit et l'opt-in qu'à des utilisateurs qui ont déjà, sur le plan organisationnel, le droit de consulter l'intégralité de ces données.

Activité, quota et alertes

Réglages de journalisation, quota d'appels et alerte email au-dessus du journal d'activité

L'onglet Activité MCP trace les appels reçus par le serveur MCP externe : qui a appelé quel outil, quand, et avec quel résultat.

Réglages disponibles (avec leurs valeurs par défaut)

Réglage Défaut Effet
Journaliser les appels MCP Activé Sans journal, aucune trace de ce qu'un agent a consulté
Enregistrer les paramètres des appels Activé Les paramètres indiquent quelles données ont été demandées ; peuvent contenir des données personnelles — désactivable séparément pour la confidentialité (les résultats, eux, ne sont jamais enregistrés)
Conservation du journal 90 jours Au-delà, les lignes sont supprimées lors de la purge
Limite d'appels par utilisateur 0 (désactivée), fenêtre de 60 minutes Nombre maximum d'appels d'outils autorisés sur la période glissante ; 0 désactive la limite
Seuil d'alerte 0 (désactivé) Envoie un courriel à l'administrateur quand un utilisateur atteint ce nombre d'appels sur la période
Délai entre deux alertes (cooldown) 720 minutes (12h) Pour un même utilisateur, évite qu'une session intensive ne déclenche des dizaines de courriels

Un bouton « Purger selon la conservation » permet de déclencher manuellement la suppression des entrées au-delà de la durée configurée.

À savoir sur le quota

Le quota ne compte que les outils réellement exécutés (tools/call avec succès) : la connexion (initialize) et la liste des outils disponibles (tools/list) ne consomment rien du quota. Un échec de comptage en base est volontairement fail-open (n'échoue pas la requête) : ce mécanisme est un garde-fou de volume, pas une garantie de sécurité anti-exfiltration.

Important : pour garder un quota ou une alerte utiles, laissez la journalisation globale activée — la désactiver arrête aussi les compteurs de quota et d'alerte. Désactivez uniquement l'enregistrement des paramètres si votre politique de confidentialité l'exige.

Journal d'activité emMCP listant les appels d'outils reçus, avec utilisateur, méthode, durée et paramètres

Le tableau « 100 derniers appels » est filtrable par utilisateur et par outil, et affiche la date, l'utilisateur, la méthode MCP, l'outil appelé, la durée et l'état (succès, refus, erreur).

Dépannage

Erreur 401 juste après le consentement OAuth

C'est le problème le plus fréquent, généralement dû à l'en-tête HTTP Authorization non transmis par défaut sous Apache en mode CGI/FPM (mod_php classique n'est pas concerné), ou à un reverse proxy HTTPS devant votre serveur qui le filtre. Le module inclut des règles .htaccess (RewriteRule et SetEnvIfNoCase pour réexposer HTTP_AUTHORIZATION / REDIRECT_HTTP_AUTHORIZATION), mais le .htaccess ne fonctionne que là où l'hébergeur l'autorise — ce n'est pas garanti sur tous les hébergements. Si l'erreur persiste :

  1. Vérifiez que le .htaccess du module est bien pris en compte (AllowOverride doit être autorisé sur le dossier custom/emmcp/ — certains hébergements mutualisés le désactivent)
  2. Si vous gérez vous-même le vhost Apache, CGIPassAuth On est le correctif le plus robuste, au niveau serveur — à ajouter dans le bloc <VirtualHost> ou <Directory> concerné : 
    <Directory "/chemin/vers/dolibarr/htdocs/custom/emmcp">
    CGIPassAuth On
</Directory>
    Sur un hébergement mutualisé, demandez à votre hébergeur/administrateur de l'activer si vous ne pouvez pas éditer le vhost vous-même.
  3. Sous Nginx + PHP-FPM, ajoutez fastcgi_param HTTP_AUTHORIZATION $http_authorization; à votre configuration si nécessaire
  4. Derrière un reverse proxy HTTPS ou un load balancer, vérifiez qu'il transmet explicitement l'en-tête Authorization de bout en bout — certains proxies le filtrent par défaut
  5. Sous Apache en mode mod_php, ce problème ne se produit normalement pas

Le connecteur claude.ai ne trouve pas la configuration OAuth

Vérifiez que l'URL du connecteur pointe bien vers mcp.php (pas vers une autre page), et que votre Dolibarr est bien accessible en HTTPS avec un certificat valide — HTTPS est obligatoire, pas optionnel.

Les outils SQL n'apparaissent pas pour un utilisateur

Rappel des quatre conditions : interrupteur global, droit Dolibarr, opt-in individuel, absence de blocage Multicompany. Il suffit qu'une seule condition manque pour que l'outil reste invisible — vérifiez les quatre dans l'ordre.

Un appel est refusé alors que l'utilisateur semble avoir les droits

Consultez le journal d'activité (onglet Activité MCP) : la colonne État indique si l'appel a réussi, a été refusé, ou a échoué. Un refus d'outil SQL peut venir d'une colonne sensible détectée, d'une syntaxe non-SELECT, ou d'un dépassement de plafond (lignes/temps/taille).

Le quota semble se déclencher trop vite (ou jamais)

Vérifiez que la journalisation globale est bien activée : la désactiver arrête aussi le comptage du quota et des alertes, même si la limite est configurée à une valeur non nulle.

Limites connues

  • L'outil de requête SQL directe est réservé à MySQL/MariaDB — PostgreSQL n'est pas supporté pour cet outil (les autres outils, basés sur l'API REST Dolibarr, ne sont pas concernés par cette limite du moteur SQL).
  • Pas de bouton de révocation OAuth ciblée : régénérez la clé pour un client authentifié par clé API ; pour bloquer immédiatement un connecteur OAuth, désactivez l'utilisateur associé ou le module. La rotation de la clé API ne révoque pas les jetons OAuth.
  • Les garde-fous SQL (plafonds, colonnes refusées, gates) réduisent le risque mais ne constituent pas une garantie absolue : n'accordez cet accès qu'à des utilisateurs qui ont déjà, organisationnellement, le droit de voir l'intégralité de ces données.

FAQ

Avec quels clients emMCP fonctionne-t-il ?

Claude.ai (connecteur personnalisé avec OAuth 2.1), Claude Code (authentification par clé API), et tout client MCP compatible avec le transport HTTP (Streamable).

emMCP dépend-il du module Dalfred ?

Non. emMCP est un module autonome, livré avec ses propres dépendances (serveur MCP, gestion OAuth, moteur SQL). Aucune installation préalable d'un autre module E-dem n'est nécessaire.

Quelles permissions l'agent obtient-il sur mes données ?

Pour les outils métier standards, celles de l'utilisateur Dolibarr utilisé pour la connexion, appliquées par l'API REST. L'accès SQL optionnel est une exception : son droit dédié et son opt-in autorisent une lecture plus large, sans les restrictions métier habituelles. Ne l'accordez qu'à des utilisateurs habilités à consulter ces données.

L'accès SQL est-il activé par défaut ?

Non. Il est désactivé par défaut et nécessite un interrupteur global, un droit Dolibarr dédié, un opt-in individuel par utilisateur, et l'absence de blocage Multicompany — les quatre conditions doivent être réunies.

Que couvre le prix affiché sur le DoliStore ?

L'achat du module (15,00 € HT) inclut 1 an de mises à jour et de téléchargements depuis le DoliStore.

Mes données restent-elles dans Dolibarr ?

Non, pas exclusivement. emMCP tourne bien sur votre serveur, mais son rôle est justement de transmettre les données demandées au client IA connecté (claude.ai, Claude Code, ou un autre) pour qu'il puisse répondre. Ces données quittent donc Dolibarr vers le fournisseur IA choisi, selon les conditions de ce fournisseur — ce n'est pas propre à emMCP, c'est le principe même du protocole MCP.

Où trouver de l'aide ?

  • Support E-dem : Contactez-nous pour toute question technique
  • Documentation MCP : modelcontextprotocol.io pour les spécifications du protocole
  • Voir aussi : Dalfred, notre agent IA intégré à Dolibarr avec sa propre interface conversationnelle et son propre accès MCP