🚀 mcp-dolibarr

Highly performant and secure MCP (Model Context Protocol) server based on FastMCP, allowing any AI assistant (Claude Desktop, Cursor, AI Agents) to interact natively with the Dolibarr ERP/CRM via its official REST API.

✨ Main Features

The MCP server covers all of Dolibarr's business management needs through more than 30 dedicated tools spread across 12 modules:

• 🏢 Third Parties & Companies (tools/thirdparties.py): Listing, full-text search by name, detailed consultation by ID, creation and partial update of customer/prospect records.

• 👤 Contacts & Individuals (tools/contacts.py): Listing and creation of contacts (individuals) linked to companies.

• 📦 Products & Services (tools/products.py): Complete catalog of items and services, search by reference, creation, update, and management of pre-tax prices / VAT rates.

• 📄 Quotes & Commercial Proposals (tools/proposals.py): Creation of multi-line quotes, validation, update/delete of lines, and automatic conversion.

• 🛒 Customer Orders (tools/orders.py): Generation of orders from a validated quote, consultation and fine-grained modification of order lines.

• 💳 Invoices & Payments (tools/invoices.py): Creation of invoices from an order or directly, final validation, and management of invoice lines.

• 📊 Stock by Warehouse (tools/stocks.py): Instant consultation of a product's actual stock levels, warehouse by warehouse.

• 📁 Projects (tools/projects.py): Creation, consultation, and attachment of projects to customer records.

• 📜 Contracts (tools/contracts.py): Tracking of service contracts and creation for a third party.

• 🛠️ Intervention Reports (tools/interventions.py): Management of technical field intervention reports.

• 📑 Documents & PDF (tools/documents.py): Automated generation of official PDFs (Azur, Crabe, etc. models) and download with Base64 encoding.

• 🔌 Direct REST API (Fallback Mode) (tools/raw.py): call_dolibarr_api tool allowing direct querying of any Dolibarr REST route not covered by a dedicated tool.

Related MCP server: MCP Server for Odoo

🌟 What mcp-dolibarr offers compared to other MCP servers

Unlike basic or generic MCP gateways, this server brings decisive added value:

1. 🔄 Complex Orchestration in a Single Call (convert_proposal_to_invoice): Instead of forcing the AI to make 4 successive manual requests, the orchestrator tool automatically chains: Validated quote $\rightarrow$ Customer order $\rightarrow$ Invoice $\rightarrow$ Invoice validation.

2. ✏️ Granular Line Manipulation (Add / Update / Delete): Full support for line-by-line management on quotes, orders, and invoices (adding items, modifying quantities/prices/labels, deleting lines).

3. 🛡️ Native Security / Read-Only Mode (READ_ONLY=true): Ability to restrict the server to read-only consultation for sensitive production environments. All write requests (POST, PUT, DELETE) are intercepted and rejected at the source.

4. 🔁 Resilience and Exponential Backoff (HTTP 429): Intelligent handling of Dolibarr API rate limits: automatically retries with delay (1s, 2s, 4s) in case of overload without causing the AI agent to fail.

5. 🎯 Cleaning and Formatting Optimized for LLM:

   • Raw JSON responses from Dolibarr (often riddled with +50 useless internal fields) are cleaned and summarized into clear, readable text.

   • Strict upstream validation (emails, positive amounts, required fields) to avoid sending malformed requests to Dolibarr.

6. 📄 Real PDF File Generation and Extraction: Allows ordering the generation of regulatory PDFs and retrieving their Base64-encoded content for the AI agent.

7. 🌐 Native Multi-Transport (stdio, http, sse, streamable-http): Works both locally on a computer (Claude Desktop, Cursor) and as a containerized microservice on a cloud server.

🏃 How to Launch and Run the MCP Server (Run)

1. Preparing the Local Environment

# 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

In the .env file, configure access to your Dolibarr instance:

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. Starting the MCP Server

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

Simple launch in the terminal:

python server.py

To connect Claude Desktop, add the following configuration to your claude_desktop_config.json file:

{
  "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. Remote Server Mode http / Streamable HTTP

To expose the MCP server via HTTP (for example on a remote server or a cloud container):

MCP_TRANSPORT=http MCP_PORT=8000 python server.py

The server will be accessible at http://0.0.0.0:8000.

3. Running with Docker

Via Docker Compose (Recommended)

docker-compose up -d --build

Via Docker CLI

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

🧪 Running Unit Tests

The unit test suite validates the behavior of the client and tools using pytest and the respx HTTP mock (no real network calls or modifications on your Dolibarr):

pytest

📁 Project Architecture and Structure

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