Skip to content

About

Model Context Protocol server for Dolibarr ERP/CRM

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Dolibarr MCP Server

Serveur MCP (Model Context Protocol) permettant à un LLM ou agent IA d'interagir avec une instance Dolibarr via son API REST.

Caractéristiques

  • Découverte dynamique : Explore automatiquement les modules et endpoints via Swagger/OpenAPI
  • 21 outils MCP : CRUD, gestion de documents, workflow commercial, projets/temps, contacts, extrafields, SQL lecture seule (optionnel)
  • Compatible Dolibarr v18-22+ : S'adapte à votre version
  • Modules custom : Fonctionne avec les modules tiers
  • Double transport : stdio (CLI) ou HTTP (web)

Architecture

LLM ←→ MCP Server (PHP) ←→ API REST Dolibarr
              ↓
       Swagger Schema (découverte dynamique)

Prérequis

  • PHP 8.1+
  • Composer
  • Une instance Dolibarr avec l'API REST activée
  • Une clé API Dolibarr (DOLAPIKEY)

Installation

git clone https://github.com/momodemo333/dolibarr-mcp-server.git
cd dolibarr-mcp-server

php8.1 $(which composer) install

cp .env.example .env
# Éditer .env avec vos valeurs

Configuration

Variables d'environnement

Créez un fichier .env à la racine :

DOLIBARR_URL=https://votre-instance-dolibarr.com
DOLIBARR_API_KEY=votre_cle_api

Configuration Claude Desktop

Ajoutez dans la configuration MCP :

Linux : ~/.config/claude/claude_desktop_config.json macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dolibarr": {
      "command": "php8.1",
      "args": ["/chemin/vers/dolibarr-mcp-server/bin/server.php"],
      "env": {
        "DOLIBARR_URL": "https://votre-instance-dolibarr.com",
        "DOLIBARR_API_KEY": "votre_cle_api"
      }
    }
  }
}

Configuration MCP JSON

Un fichier .mcp.json.example est fourni comme modèle pour les clients compatibles MCP. Copiez-le localement et adaptez les chemins/variables sans jamais committer vos credentials.

Outils disponibles

CRUD générique (6 outils)

Outil Description
dolibarr_api_explorer Découvrir modules, endpoints et paramètres
dolibarr_list Lister les ressources avec filtres et pagination
dolibarr_get Récupérer une ressource par ID
dolibarr_create Créer une ressource
dolibarr_update Mettre à jour une ressource
dolibarr_delete Supprimer une ressource

Workflow commercial (3 outils)

Outil Description
dolibarr_action Exécuter une action (validate, close, reopen...)
dolibarr_add_line Ajouter des lignes aux devis, commandes, factures
dolibarr_create_from Créer un document depuis un autre (devis → commande → facture)

Gestion des contacts (2 outils)

Outil Description
dolibarr_link_contact Lier/délier un contact à un document (BILLING, SHIPPING, CUSTOMER)
dolibarr_get_contacts Lister les contacts liés à un document

Projets / temps (1 outil)

Outil Description
dolibarr_add_time_spent Ajouter une ligne de temps sur une tâche projet (date seule ou avec heure, produit) ; refuse ce que l'API du cœur ignorerait
dolibarr_update_time_spent Modifier une ligne de temps existante (date avec ou sans heure, durée, note, produit) ; ligne facturée refusée

Gestion documentaire (5 outils)

Outil Description
dolibarr_documents_list Lister les documents attachés
dolibarr_documents_upload Uploader un document
dolibarr_documents_download Télécharger un document
dolibarr_documents_builddoc Générer un PDF
dolibarr_documents_delete Supprimer un document

Extrafields (2 outils)

Outil Description
dolibarr_extrafield_update Modifier un champ personnalisé
dolibarr_extrafield_delete Supprimer un champ personnalisé

SQL lecture seule (2 outils, optionnels)

Outil Description
dolibarr_sql_query Exécuter une requête SQL en lecture seule (reporting : CA par tiers, par mois, top produits…)
dolibarr_sql_schema Lister les tables et colonnes lisibles, pour écrire des requêtes correctes

⚠️ Sécurité — désactivé par défaut. Ces deux outils ne sont pas enregistrés par les points d'entrée stdio et HTTP standard : ils n'apparaissent même pas dans tools/list. Ils ne deviennent disponibles que si le module hôte (Dalfred, emMCP…) injecte explicitement une capacité SQL (SqlCapabilityInterface) après avoir vérifié que l'utilisateur courant y a droit. Le refus par défaut est donc structurel, pas un simple contrôle à l'exécution.

Même une fois activée, la fonctionnalité reste strictement bornée : un seul statement, SELECT/WITH uniquement (aucune écriture ni DDL), colonnes de credentials (api_key, pass_crypted, token_hash…) refusées partout, SELECT * interdit dès qu'une table sensible (llx_user, llx_socpeople, llx_adherent) est référencée, tables système et tables d'authentification inaccessibles, LIMIT toujours imposé par le serveur (200 lignes par défaut), timeout et plafond de taille de réponse appliqués par l'hôte, qui journalise également chaque requête.

Modules supportés

thirdparties, contacts, products, invoices, supplierinvoices, orders, supplierorders, proposals, categories, users, projects, contracts, et tous les modules activés dans votre instance.

Exemples d'utilisation

"Explore les modules disponibles dans Dolibarr"
"Liste les 10 dernières factures"
"Crée un devis pour le client X avec 2 lignes"
"Valide la commande 123"
"Génère le PDF de la facture F2501942"
"Lie le contact Dupont à la commande comme contact facturation"

Structure du projet

dolibarr-mcp-server/
├── bin/
│   └── server.php                # Point d'entrée MCP (stdio)
├── public/
│   └── index.php                 # Point d'entrée HTTP
├── src/
│   ├── Bootstrap.php             # Chargement env + construction serveur
│   ├── Container.php             # Conteneur DI (PSR-11)
│   ├── Client/
│   │   ├── DolibarrClient.php    # Client HTTP pour l'API Dolibarr
│   │   └── ApiSchemaClient.php   # Parser Swagger/OpenAPI
│   ├── Support/
│   │   └── FieldMapper.php       # Auto-correction des noms de champs
│   └── Tools/
│       ├── CrudTools.php         # CRUD générique (list, get, create, update, delete)
│       ├── ExplorerTools.php     # Découverte API
│       ├── ActionTools.php       # Actions workflow (validate, close...)
│       ├── LineTools.php         # Gestion des lignes + création depuis document
│       ├── ContactTools.php      # Liaison contacts ↔ documents
│       ├── DocumentTools.php     # Gestion documentaire (PDF, upload, download)
│       └── ExtrafieldTools.php   # Champs personnalisés
├── tests/
│   ├── Support/
│   │   └── FieldMapperTest.php
│   └── Tools/
│       ├── CrudToolsTest.php
│       ├── ActionToolsTest.php
│       ├── LineToolsTest.php
│       ├── ContactToolsTest.php
│       ├── DocumentToolsTest.php
│       └── ExtrafieldToolsTest.php
├── .env.example                  # Template variables d'environnement
├── .mcp.json.example             # Template config MCP
├── composer.json
├── phpunit.xml
├── LLM.md                        # Guide complet des outils pour LLM
├── CHANGELOG.md
└── README.md

Tests

php8.1 vendor/bin/phpunit

Documentation complémentaire

  • LLM.md — Guide détaillé des outils avec paramètres, exemples et bonnes pratiques
  • CHANGELOG.md — Historique des versions

Compatibilité

Composant Version
Dolibarr v18.0+ (testé jusqu'à v22)
PHP 8.1+
MCP Protocol 2024-11-05
SDK php-mcp/server ^3.3

License

MIT

Extensions (outils d'autres modules)

Depuis 2.7.0, l'hôte (emMCP, Dalfred) peut ajouter des outils fournis par d'autres modules Dolibarr : il passe à Bootstrap::handleHttpRequest() une liste d'objets DolibarrMcp\Extension\ToolExtension. Chaque extension fournit des objets dont les méthodes publiques portent #[McpTool] et #[Schema], comme les classes d'outils de ce paquet. Le préfixe dolibarr_ est réservé aux outils intégrés.

About

Model Context Protocol server for Dolibarr ERP/CRM

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages