Version 1.10.2. Expose une instance Dolibarr comme serveur MCP (Model
Context Protocol, transport Streamable HTTP) consommable par claude.ai,
Claude Desktop, ChatGPT (connecteurs OAuth), Claude Code, l'API Anthropic
(mcp_servers) et tout client MCP compatible HTTP.
emMCP est un module autonome : il embarque son propre moteur MCP et ses dépendances, isolées (voir plus bas). Aucun autre module E-dem n'est requis.
- Dolibarr 17.0 ou plus récent ; PHP 8.1 ou plus récent.
- Module API REST de Dolibarr activé (les outils passent par lui).
- Accès en HTTPS (obligatoire pour les connecteurs OAuth).
- MySQL ou MariaDB pour l'option de requêtes SQL en lecture seule (les autres outils fonctionnent quelle que soit la base).
- Téléchargez le ZIP (DoliStore ou https://www.e-dem.com) et décompressez-le
dans
htdocs/custom/: le dossier final esthtdocs/custom/emmcp/. Le ZIP contient déjà toutes les dépendances (vendor/) : rien d'autre à installer. - Activez emMCP dans Accueil > Configuration > Modules/Applications (ainsi que le module API REST s'il ne l'est pas).
- Ouvrez la configuration du module : l'onglet Paramètres affiche l'URL exacte du connecteur et des exemples prêts à copier.
Mise à jour : décompressez la nouvelle version par-dessus l'ancienne. Les tables du module sont migrées automatiquement à la première requête qui suit ; inutile de désactiver/réactiver le module ou de repasser par les onglets. Vérifiez la version et la ligne « Schéma de base » dans l'onglet Diagnostic.
- Paramètres : URL du serveur MCP, méthodes d'authentification, état du
module API REST et du moteur MCP, exemples pour claude.ai, Claude Code et un
client MCP générique (
mcp.json). - Accès SQL MCP : interrupteur global, plafonds (lignes, durée, taille), journalisation par empreinte seule, exception multi-société, liste des utilisateurs autorisés (voir plus bas).
- Activité MCP : journal des appels (paramètres enregistrés ou non, durée de conservation, purge), limite d'appels par utilisateur, seuil d'alerte par courriel, destinataire de l'alerte, délai entre deux alertes.
- Accès accordés : chaque client connecté par OAuth (utilisateur, client, dates d'octroi, de renouvellement et d'expiration) avec un bouton Révoquer qui coupe l'accès immédiatement.
- Diagnostic : vérifications, journal des connexions et rapport pour le support (voir plus bas).
- À propos.
- Endpoint unique :
https://<instance>/custom/emmcp/mcp.php - Par requête (PHP-FPM/Apache) : pas de daemon, pas de ReactPHP.
Chaque POST JSON-RPC est traité par le SDK PHP officiel MCP (
mcp/sdk), les sessions MCP sont persistées dansdocuments/emmcp/sessions/. - Authentification, deux voies :
- Clé API d'un utilisateur Dolibarr, via
Authorization: Bearer <clé>(recommandé) ou headerDOLAPIKEY— pour Claude Code, l'API Anthropic, et tout client MCP acceptant un header custom. - OAuth 2.1 (
oauth.php) — pour les connecteurs claude.ai, Claude Desktop et ChatGPT qui n'acceptent qu'OAuth : découverte automatique (RFC 9728 + RFC 8414), enregistrement dynamique du client (RFC 7591), code d'autorisation avec PKCE S256, rotation des refresh tokens. L'utilisateur se connecte avec son compte Dolibarr et consent ; aucune clé à copier. Dans les deux cas, les tools agissent via l'API REST Dolibarr avec les permissions de l'utilisateur.
- Clé API d'un utilisateur Dolibarr, via
- Tools : ceux du moteur
dolibarr-mcp-server
embarqué — CRUD générique (
dolibarr_list,dolibarr_get,dolibarr_create,dolibarr_create_from,dolibarr_update,dolibarr_delete), lignes de documents, temps passé (dolibarr_add_time_spent,dolibarr_update_time_spent), actions métier, contacts, extrafields, documents et génération PDF, création de fichiers, informations sur l'instance (dolibarr_environment) et explorateur d'API —, plus deux tools de requêtes SQL en lecture seule désactivés par défaut (voir ci-dessous) et ceux qu'ajoutent d'autres modules (voir Extensions).
Deux tools supplémentaires — dolibarr_sql_schema et dolibarr_sql_query —
permettent à l'agent d'introspecter le schéma et d'exécuter des requêtes de
reporting (SELECT, WITH/CTE, JOIN, sous-requêtes, agrégats, UNION) sur
les tables métier, y compris celles des modules tiers.
Contrairement aux autres tools, qui passent par l'API REST et héritent donc des permissions Dolibarr de l'appelant, une requête SQL n'hérite de rien. L'accès est donc reconstruit explicitement et quatre conditions doivent toutes être réunies :
- la fonctionnalité est activée globalement (onglet Accès SQL MCP de la configuration du module) ;
- l'utilisateur détient le droit Dolibarr Exécuter des requêtes SQL en lecture seule via MCP — être administrateur ne suffit pas, le droit doit être attribué ;
- l'utilisateur est explicitement coché dans la liste de l'onglet Accès SQL MCP ;
- le module multicompany n'est pas actif (ou l'exception a été activée) — une requête SQL traverse les lignes de toutes les entités, elle ne peut pas être filtrée par entité de façon fiable.
Tant que ces conditions ne sont pas réunies, les deux tools n'apparaissent pas du tout dans la liste des tools exposés au client MCP.
Garde-fous en place : une seule instruction par appel, aucune écriture ni DDL,
aucune lecture verrouillante (FOR UPDATE, FOR SHARE, LOCK IN SHARE MODE),
colonnes de credentials refusées où qu'elles apparaissent — noms exacts et
motifs, donc smtp_password ou access_token aussi bien que api_key —,
SELECT * accepté seulement si aucune des colonnes qu'il recouvre n'est
sensible (sinon refusé en nommant la colonne), requêtes
limitées à la base courante (autre_base.llx_societe refusé), commentaires
exécutables et optimizer hints refusés, tables d'authentification et de session
inaccessibles, exécution sur une connexion dédiée en transaction de lecture
seule avec un sql_mode normalisé et un timeout obligatoire, plafonds de lignes
et de taille imposés par le serveur, et journal d'audit
(llx_emmcp_sql_audit) qui n'enregistre jamais les résultats.
Le tool d'introspection du schéma permet à l'agent de choisir les colonnes dont il a besoin.
Aucun compte MySQL supplémentaire n'est à créer (depuis la 1.3.0) : les
requêtes utilisent les identifiants de Dolibarr, sur une session mysqli
séparée, de sorte que le timeout, le sql_mode et la transaction en lecture
seule ne débordent jamais sur la connexion de l'application. Une transaction
en lecture seule n'empêche pas le DDL : la lecture seule est donc garantie par
le logiciel (analyse lexicale, analyseur SQL avec liste blanche de clauses,
politique sur chaque table, colonne et fonction, contrôle final que
l'instruction commence par SELECT ou WITH).
claude mcp add dolibarr --transport http \
https://<instance>/custom/emmcp/mcp.php \
--header "Authorization: Bearer VOTRE_CLE_API"Dans claude.ai : Paramètres → Connecteurs → « Ajouter un connecteur
personnalisé », URL https://<instance>/custom/emmcp/mcp.php. Claude
découvre l'OAuth, ouvre la page de connexion Dolibarr et l'écran de
consentement, puis se connecte — sans clé à saisir.
Les connecteurs ajoutés dans claude.ai sont aussi disponibles dans Claude Desktop. Pour retirer un accès donné par OAuth : onglet Accès accordés, bouton Révoquer ; supprimer la clé API REST de l'utilisateur ou désactiver son compte met aussi fin à tous les accès OAuth qu'il a donnés, et seule la désactivation du compte l'empêche de se reconnecter.
Dans ChatGPT (mode développeur → créer un connecteur / une app, authentification
OAuth, champs Client ID et Client secret vides), l'URL est la même :
https://<instance>/custom/emmcp/mcp.php. Aucune règle de serveur web n'est
nécessaire.
Testé de bout en bout le 16/11/2026 (emMCP 1.7.0, sans aucune règle à la racine du domaine). Le journal d'accès du serveur montre la séquence de ChatGPT :
POST mcp.php→ 401, avec l'en-têteWWW-Authenticate;- ChatGPT suit cet en-tête :
GET oauth.php/.well-known/oauth-protected-resource→ 200 ; - il essaie d'abord la racine du domaine
(
/.well-known/oauth-authorization-server/custom/emmcp/oauth.php→ 404), puis se replie de lui-même sur les adresses du module (oauth.php/.well-known/oauth-authorization-serveret…/openid-configuration→ 200) ; POST oauth.php/register(enregistrement dynamique) → 201, connexion Dolibarr et consentement,POST oauth.php/token→ 200, puis appelsmcp.php→ 200.
Les 404 à la racine du domaine sont donc normaux et sans effet.
Les requêtes de découverte de ChatGPT (étapes 1 à 3) portent le User-Agent
Python/3.14 aiohttp/…. Certains pare-feu d'hébergement (règles ModSecurity) le
refusent avec un 403 ou un 406, alors que le navigateur, curl et les étapes
suivantes de ChatGPT passent. ChatGPT affiche alors « Impossible de détecter les
paramètres OAuth », bien que le module réponde correctement.
Test, depuis n'importe quelle machine :
curl -A "aiohttp/3.14" -i https://<instance>/custom/emmcp/oauth.php/.well-known/oauth-protected-resourceLa réponse doit être 200 avec un JSON qui contient "resource", pas 403 ni
406. Si elle est refusée, demandez à l'hébergeur de ne plus bloquer ce
User-Agent pour le site (ou désactivez la règle dans le pare-feu applicatif de
Plesk si vous gérez le serveur). Le bouton « Vérifier l'en-tête Authorization et
la découverte OAuth » de l'onglet Diagnostic fait le même test depuis le
serveur lui-même : un refus y est une preuve ; un succès est un bon indice, car
un pare-feu placé en amont, ou qui exempte les adresses locales, peut traiter
autrement les requêtes venues d'OpenAI.
| Route | Rôle |
|---|---|
/.well-known/oauth-protected-resource |
Métadonnées de la ressource (RFC 9728) — pointées par le WWW-Authenticate du 401 de mcp.php |
/.well-known/oauth-authorization-server et /openid-configuration |
Métadonnées du serveur d'autorisation (RFC 8414) |
/register |
Enregistrement dynamique de client (RFC 7591) |
/authorize |
Login Dolibarr natif + écran de consentement |
/token |
Échange de code (PKCE S256) et rotation des refresh tokens |
Tokens stockés en base sous forme de hash sha256 uniquement
(llx_emmcp_oauth_token) ; access token 1 h, refresh token 30 j.
Onglet Diagnostic de la configuration du module : vérifications (module
API REST, schéma, moteur MCP et isolation de ses dépendances, conflits de
bibliothèques, dernière erreur du moteur, URL HTTPS, accès OAuth sans clé API,
en-tête Authorization), journal des connexions (chaque étape OAuth et
chaque requête MCP refusée, avec la raison précise, 30 jours :
llx_emmcp_auth_log) et un rapport à copier pour le support, sans aucun
secret.
Dolibarr charge tous les modules dans le même processus PHP : une copie de
psr/log, guzzle ou symfony livrée par un autre module (ou par le cœur, sous
includes/) prendrait la place de la nôtre, et une version majeure différente
provoque une erreur fatale à chaque appel MCP. Le ZIP publié préfixe donc
toutes les dépendances tierces du moteur sous EmmcpVendor\ (php-scoper, voir
tools/scoper.inc.php, étape 4b de make build-release, contrôlée par
tests/runtime_isolation_test.php). Restent partagés, volontairement :
DolibarrMcp\ et Mcp\, que les modules d'extension utilisent. Pour ces deux
espaces de noms (et pour un moteur non préfixé), lib/emmcp_runtime.php
vérifie avant usage que chaque type clé vient bien du moteur et répond sinon
par une erreur JSON qui nomme le fichier fautif.
- Découverte des tools re-scannée à chaque requête (pas de cache PSR-16).
- Pas de gestion multi-entité (multicompany). L'accès SQL en lecture seule est d'ailleurs refusé hors entité 1 tant que l'exception n'est pas activée.
- Portée OAuth unique (
dolibarr) : pas encore de granularité par scope. - Les requêtes SQL en lecture seule nécessitent MySQL ou MariaDB (PostgreSQL n'est pas pris en charge par cette fonctionnalité).
Depuis la 1.8.0, un autre module Dolibarr peut ajouter ses propres outils MCP sans
modifier emMCP : il déclare le contexte de hook emmcp et implémente
emmcpRegisterTools($parameters, &$object, &$action, $hookmanager). Il y ajoute à
$parameters['collector'] (un ArrayObject) un objet \DolibarrMcp\Extension\ToolExtension.
$parameters['user'] est l'utilisateur de la session MCP, droits chargés : les
outils de l'extension s'exécutent dans Dolibarr en son nom et doivent vérifier ses droits.
Exemple : le module emMCP Extensions (outils Todo).
- Point de départ : l'onglet Diagnostic. Une ligne en alerte et la raison indiquée dans le journal des connexions désignent en général la cause.
- Après une mise à jour par décompression depuis une version 1.10.1 ou antérieure, rien n'a changé (Diagnostic affiche l'ancienne version, comportement incohérent) : le cache d'opcodes de PHP (opcache) peut encore servir l'ancien code. Redémarrez PHP (PHP-FPM, ou Apache si PHP tourne en module), ou demandez-le à votre hébergeur. Corrigé à partir de la 1.10.2 : chaque version porte désormais ses propres dates de fichiers.
- Tables du module : elles sont migrées automatiquement à la première requête qui suit une mise à jour ; il n'est pas nécessaire de repasser par les onglets. La ligne « Schéma de base » du Diagnostic doit être « OK ».
- ChatGPT : voir Dépannage : « Impossible de détecter les paramètres OAuth » plus haut.
- Support : support@e-dem.com — https://www.e-dem.com. Joignez le Rapport pour le support de l'onglet Diagnostic (il ne contient aucun secret).