{"type": "text"}

🚀 mcp-dolibarr

Hochleistungsfähiger und sicherer MCP-Server (Model Context Protocol) auf Basis von FastMCP, der es jedem KI-Assistenten (Claude Desktop, Cursor, AI Agents) ermöglicht, nativ über die offizielle REST-API mit der ERP/CRM-Software Dolibarr zu interagieren.

✨ Hauptfunktionen

Der MCP-Server deckt den gesamten betriebswirtschaftlichen Bedarf in Dolibarr mit mehr als 30 speziellen Werkzeugen ab, die auf 12 Module verteilt sind:

• 🏢 Geschäftspartner & Firmen (tools/thirdparties.py): Auflistung, Volltextsuche nach Name, detaillierte Ansicht nach ID, Erstellung und teilweise Aktualisierung von Kunden-/Interessentendatensätzen.

• 👤 Kontakte & Ansprechpartner (tools/contacts.py): Auflistung und Erstellung von Kontakten (natürliche Personen), die Firmen zugeordnet sind.

• 📦 Produkte & Dienstleistungen (tools/products.py): Vollständiger Katalog von Artikeln und Dienstleistungen, Suche nach Referenz, Erstellung, Aktualisierung und Verwaltung von Nettopreisen / Mehrwertsteuersätzen.

• 📄 Angebote & kommerzielle Vorschläge (tools/proposals.py): Erstellung mehrzeiliger Angebote, Validierung, Aktualisierung/Löschung von Positionen und automatische Konvertierung.

• 🛒 Kundenaufträge (tools/orders.py): Erzeugung von Aufträgen aus einem validierten Angebot, Ansicht und feine Bearbeitung von Auftragspositionen.

• 💳 Rechnungen & Zahlungen (tools/invoices.py): Erstellung von Rechnungen aus einem Auftrag oder direkt, abschließende Validierung und Verwaltung von Rechnungspositionen.

• 📊 Lagerbestände nach Lager (tools/stocks.py): Sofortige Abfrage der tatsächlichen Lagerbestände eines Produkts, Lager für Lager.

• 📁 Projekte (tools/projects.py): Erstellung, Ansicht und Zuordnung von Projekten zu Kundendatensätzen.

• 📜 Verträge (tools/contracts.py): Verwaltung von Dienstleistungsverträgen und Erstellung für einen Geschäftspartner.

• 🛠️ Einsatzberichte (tools/interventions.py): Verwaltung von technischen Einsatzberichten vor Ort.

• 📑 Dokumente & PDFs (tools/documents.py): Automatisierte Erstellung offizieller PDFs (Vorlagen Azur, Crabe usw.) und Herunterladen mit Base64-Kodierung.

• 🔌 Direkte REST-API (Notfallmodus) (tools/raw.py): Werkzeug call_dolibarr_api zum direkten Abfragen beliebiger REST-Routen von Dolibarr, die nicht von einem speziellen Werkzeug abgedeckt werden.

Related MCP server: Dolibarr MCP Server

🌟 Was mcp-dolibarr gegenüber anderen MCP-Servern zusätzlich bietet

Im Gegensatz zu einfachen oder generischen MCP-Gateways bietet dieser Server einen entscheidenden Mehrwert:

1. 🔄 Komplexe Orchestrierung in einem einzigen Aufruf (convert_proposal_to_invoice): Anstatt die KI zu zwingen, 4 aufeinanderfolgende manuelle Anfragen durchzuführen, verarbeitet das Orchestrierungswerkzeug automatisch: Validiertes Angebot $\rightarrow$ Kundenauftrag $\rightarrow$ Rechnung $\rightarrow$ Rechnungsvalidierung.

2. ✏️ Detaillierte Bearbeitung von Positionen (Hinzufügen / Aktualisieren / Löschen): Vollständige Unterstützung der positionsweisen Verwaltung bei Angeboten, Aufträgen und Rechnungen (Hinzufügen von Artikeln, Ändern von Mengen/Preisen/Bezeichnungen, Löschen von Positionen).

3. 🛡️ Nativer Sicherheits- / Schreibschutzmodus (READ_ONLY=true): Möglichkeit, den Server für sensible Produktionsumgebungen auf reine Leseansicht zu beschränken. Alle Schreibanfragen (POST, PUT, DELETE) werden abgefangen und an der Quelle abgewiesen.

4. 🔁 Ausfallsicherheit und exponentielles Backoff (HTTP 429): Intelligente Verwaltung der Ratenbegrenzungen der Dolibarr-API: Bei Überlastung wird automatisch mit Wartezeit (1s, 2s, 4s) erneut versucht, ohne den KI-Agenten scheitern zu lassen.

5. 🎯 Für LLMs optimierte Bereinigung und Formatierung:

   • Die rohen JSON-Antworten von Dolibarr (oft mit über 50 unnötigen internen Feldern durchsetzt) werden bereinigt und in klaren, lesbaren Text zusammengefasst.

   • Strenge Vorabvalidierung (E-Mails, positive Beträge, Pflichtfelder), um fehlerhafte Anfragen an Dolibarr zu vermeiden.

6. 📄 Echte Erzeugung und Extraktion von PDF-Dateien: Ermöglicht die Anweisung zur Erstellung gesetzlich vorgeschriebener PDFs und den Abruf ihres Base64-kodierten Inhalts für den KI-Agenten.

7. 🌐 Nativer Multi-Transport (stdio, http, sse, streamable-http): Funktioniert sowohl lokal auf dem Computer (Claude Desktop, Cursor) als auch als containerisierter Mikroservice auf einem Cloud-Server.

🏃 So starten und ausführen Sie den MCP-Server (Run)

1. Vorbereitung der lokalen Umgebung

# 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

Konfigurieren Sie in der Datei .env den Zugriff auf Ihre Dolibarr-Instanz:

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. Starten des MCP-Servers

A. Lokaler Modus stdio (Claude Desktop / Cursor / VS Code)

Einfacher Start im Terminal:

python server.py

Um Claude Desktop zu verbinden, fügen Sie die folgende Konfiguration in Ihre Datei claude_desktop_config.json ein:

{
  "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. Fernserver-Modus http / Streamable HTTP

Um den MCP-Server über HTTP bereitzustellen (z. B. auf einem entfernten Server oder in einem Cloud-Container):

MCP_TRANSPORT=http MCP_PORT=8000 python server.py

Der Server ist unter http://0.0.0.0:8000 erreichbar.

3. Ausführung mit Docker

Über Docker Compose (empfohlen)

docker-compose up -d --build

Über die Docker-CLI

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

🧪 Ausführen der Unit-Tests

Die Unit-Testsuite validiert das Verhalten des Clients und der Werkzeuge mit pytest und dem HTTP-Mock respx (keine echten Netzwerkaufrufe oder Änderungen an Ihrem Dolibarr):

pytest

📁 Projektarchitektur und -struktur

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