🚀 mcp-dolibarr

Serveur MCP (Model Context Protocol) hautement performant et sécurisé basé sur FastMCP, permettant à n'importe quel assistant IA (Claude Desktop, Cursor, AI Agents) d'interagir nativement avec l'ERP/CRM Dolibarr via son API REST officielle.

---

✨ Fonctionnalités Principales

Le serveur MCP couvre l'ensemble des besoins de gestion d'entreprise sur Dolibarr à travers plus de 30 outils dédiés répartis dans 12 modules :

• 🏢 Tiers & Sociétés (tools/thirdparties.py) : Listing, recherche plein-texte par nom, consultation détaillée par ID, création et mise à jour partielle des fiches clients/prospects.
• 👤 Contacts & Intervenants (tools/contacts.py) : Listing et création des contacts (personnes physiques) rattachés à des sociétés.
• 📦 Produits & Services (tools/products.py) : Catalogue complet d'articles et services, recherche par référence, création, mise à jour et gestion des prix HT / taux de TVA.
• 📄 Devis & Propositions Commerciales (tools/proposals.py) : Création de devis multi-lignes, validation, mise à jour / suppression de lignes et conversion automatique.
• 🛒 Commandes Clients (tools/orders.py) : Génération de commandes à partir d'un devis validé, consultation et modification fine des lignes de commande.
• 💳 Factures & Règlements (tools/invoices.py) : Création de factures depuis une commande ou en direct, validation finale et gestion des lignes de facture.
• 📊 Stocks par Entrepôt (tools/stocks.py) : Consultation instantanée des niveaux de stock réel d'un produit, entrepôt par entrepôt.
• 📁 Projets (tools/projects.py) : Création, consultation et rattachement de projets aux fiches clients.
• 📜 Contrats (tools/contracts.py) : Suivi des contrats de service et création pour un tiers.
• 🛠️ Fiches d'Intervention (tools/interventions.py) : Gestion des fiches d'intervention technique sur le terrain.
• 📑 Documents & PDF (tools/documents.py) : Génération automatisée de PDF officiels (modèles Azur, Crabe, etc.) et téléchargement avec encodage Base64.
• 🔌 API Rest Directe (Mode Secours) (tools/raw.py) : Outil call_dolibarr_api permettant d'interroger directement n'importe quelle route REST de Dolibarr non couverte par un outil dédié.

---

🌟 Ce que mcp-dolibarr offre en plus par rapport aux autres serveurs MCP

Contrairement aux passerelles MCP basiques ou génériques, ce serveur apporte une valeur ajoutée déterminante :

1. 🔄 Orchestration Complexe en 1 seul appel (convert_proposal_to_invoice) : Au lieu de forcer l'IA à effectuer 4 requêtes manuelles successives, l'outil orchestrateur enchaîne automatiquement : Devis validé $\rightarrow$ Commande client $\rightarrow$ Facture $\rightarrow$ Validation de la facture.
2. ✏️ Manipulation Granulaire des Lignes (Add / Update / Delete) : Prise en charge complète de la gestion ligne par ligne sur les devis, commandes et factures (ajout d'articles, modification de quantités/prix/libellés, suppression de ligne).
3. 🛡️ Mode Sécurité / Lecture Seule Natif (READ_ONLY=true) : Possibilité de brider le serveur en consultation seule pour des environnements de production sensibles. Toutes les requêtes d'écriture (POST, PUT, DELETE) sont interceptées et rejetées à la source.
4. 🔁 Résilience et Backoff Exponentiel (HTTP 429) : Gestion intelligente des limites de débit de l'API Dolibarr : réessaye automatiquement avec temporisation (1s, 2s, 4s) en cas de surcharge sans faire échouer l'agent IA.
5. 🎯 Nettoyage et Formatage Optimisés pour LLM :
   • Les réponses JSON brutes de Dolibarr (souvent truffées de +50 champs internes inutiles) sont nettoyées et résumées en texte clair et lisible.
   • Validation stricte en amont (emails, montants positifs, champs obligatoires) pour éviter d'envoyer des requêtes malformées à Dolibarr.
6. 📄 Génération et Extraction Réelle de Fichiers PDF : Permet d'ordonner la génération des PDF réglementaires et de récupérer leur contenu encodé en Base64 pour l'agent IA.
7. 🌐 Multi-Transport Natif (stdio, http, sse, streamable-http) : Fonctionne aussi bien localement sur ordinateur (Claude Desktop, Cursor) qu'en microservice conteneurisé sur un serveur Cloud.

---

🏃 Comment Lancer et Exécuter le Serveur MCP (Run)

1. Préparation de l'environnement local

# 1. Créer l'environnement virtuel Python
python -m venv .venv

# 2. Activer l'environnement
# Linux / macOS / Git Bash :
source .venv/bin/activate
# Windows PowerShell :
# .venv\Scripts\Activate.ps1

# 3. Installer les dépendances
pip install -r requirements.txt

# 4. Configurer le fichier de variables d'environnement
cp .env.example .env

Dans le fichier .env, configurez l'accès à votre instance Dolibarr :

DOLIBARR_URL=http://localhost:8080/api/index.php
DOLIBARR_API_KEY=votre_cle_api_dolibarr
MCP_TRANSPORT=stdio
LOG_LEVEL=INFO
READ_ONLY=false

---

2. Démarrage du Serveur MCP

A. Mode Local stdio (Claude Desktop / Cursor / VS Code)

Lancement simple dans le terminal :

python server.py

Pour connecter Claude Desktop, ajoutez la configuration suivante dans votre fichier claude_desktop_config.json :

{
  "mcpServers": {
    "dolibarr": {
      "command": "python",
      "args": ["/chemin/absolu/vers/mcp-dolibarr/server.py"],
      "env": {
        "DOLIBARR_URL": "http://localhost:8080/api/index.php",
        "DOLIBARR_API_KEY": "votre_cle_api_dolibarr"
      }
    }
  }
}

B. Mode Serveur Distant http / Streamable HTTP

Pour exposer le serveur MCP via HTTP (par exemple sur un serveur distant ou un conteneur cloud) :

MCP_TRANSPORT=http MCP_PORT=8000 python server.py

Le serveur sera accessible sur http://0.0.0.0:8000.

---

3. Exécution avec Docker

Via Docker Compose (Recommandé)

docker-compose up -d --build

Via Docker CLI

docker build -t mcp-dolibarr .
docker run -d -p 8000:8000 --env-file .env mcp-dolibarr

---

🧪 Exécution des Tests Unitaires

La suite de tests unitaires valide le comportement du client et des outils à l'aide de pytest et du mock HTTP respx (aucun appel réseau réel ni modification sur votre Dolibarr) :

pytest

---

📁 Architecture et Structure du Projet

mcp-dolibarr/
├── app.py                # Initialisation de l'instance FastMCP & gestion du lifespan
├── server.py             # Point d'entrée principal (Transports stdio/http & Logging)
├── config/
│   └── settings.py       # Centralisation et validation des paramètres d'environnement (.env)
├── dolibarr/
│   ├── client.py         # Client HTTP asynchrone httpx connecté à l'API REST Dolibarr
│   ├── auth.py           # Authentification HTTP via le header DOLAPIKEY
│   └── exceptions.py     # Hiérarchie des erreurs et exceptions métier
├── tools/                # 12 modules d'outils MCP exposés aux assistants IA
│   ├── thirdparties.py   # Gestion des tiers et sociétés clients/prospects
│   ├── contacts.py       # Gestion des contacts personnes physiques
│   ├── products.py       # Catalogue produits et services
│   ├── proposals.py      # Devis & Orchestrateur de conversion devis->facture
│   ├── orders.py         # Commandes clients et gestion de leurs lignes
│   ├── invoices.py       # Facturation, validation et paiements
│   ├── stocks.py         # Suivi des niveaux de stock par entrepôt
│   ├── projects.py       # Fiches projets
│   ├── contracts.py      # Suivi des contrats clients
│   ├── interventions.py  # Fiches d'intervention technique
│   ├── documents.py      # Génération & téléchargement de PDF
│   └── raw.py            # Outil de secours API REST brute
├── utils/
│   ├── formatters.py     # Nettoyage et mise en forme des réponses JSON pour les LLM
│   └── validators.py     # Validation stricte des entrées utilisateur
├── tests/                # Tests unitaires automatisés (pytest + respx)
├── Dockerfile            # Image Docker du serveur MCP
├── docker-compose.yml    # Fichier Docker Compose
├── requirements.txt      # Liste des dépendances Python
└── README.md             # Documentation du projet