🚀 mcp-dolibarr

Servidor MCP (Model Context Protocol) de alto rendimiento y seguro basado en FastMCP, que permite a cualquier asistente de IA (Claude Desktop, Cursor, AI Agents) interactuar nativamente con el ERP/CRM Dolibarr a través de su API REST oficial.

✨ Funcionalidades Principales

El servidor MCP cubre todas las necesidades de gestión empresarial en Dolibarr a través de más de 30 herramientas dedicadas repartidas en 12 módulos:

• 🏢 Terceros y Empresas (tools/thirdparties.py): Listado, búsqueda de texto completo por nombre, consulta detallada por ID, creación y actualización parcial de las fichas de clientes/prospectos.

• 👤 Contactos e Intervinientes (tools/contacts.py): Listado y creación de contactos (personas físicas) vinculados a empresas.

• 📦 Productos y Servicios (tools/products.py): Catálogo completo de artículos y servicios, búsqueda por referencia, creación, actualización y gestión de precios sin IVA / tipo de IVA.

• 📄 Presupuestos y Propuestas Comerciales (tools/proposals.py): Creación de presupuestos de varias líneas, validación, actualización/eliminación de líneas y conversión automática.

• 🛒 Pedidos de Clientes (tools/orders.py): Generación de pedidos a partir de un presupuesto validado, consulta y modificación detallada de las líneas de pedido.

• 💳 Facturas y Pagos (tools/invoices.py): Creación de facturas desde un pedido o directamente, validación final y gestión de las líneas de factura.

• 📊 Existencias por Almacén (tools/stocks.py): Consulta instantánea de los niveles de stock real de un producto, almacén por almacén.

• 📁 Proyectos (tools/projects.py): Creación, consulta y vinculación de proyectos a las fichas de clientes.

• 📜 Contratos (tools/contracts.py): Seguimiento de los contratos de servicio y creación para un tercero.

• 🛠️ Fichas de Intervención (tools/interventions.py): Gestión de las fichas de intervención técnica sobre el terreno.

• 📑 Documentos y PDF (tools/documents.py): Generación automatizada de PDF oficiales (modelos Azur, Crabe, etc.) y descarga con codificación Base64.

• 🔌 API REST Directa (Modo de Respaldo) (tools/raw.py): Herramienta call_dolibarr_api que permite consultar directamente cualquier ruta REST de Dolibarr no cubierta por una herramienta dedicada.

Related MCP server: MCP Server for Odoo

🌟 Lo que mcp-dolibarr ofrece además en comparación con otros servidores MCP

A diferencia de las pasarelas MCP básicas o genéricas, este servidor aporta un valor añadido determinante:

1. 🔄 Orquestación compleja en 1 sola llamada (convert_proposal_to_invoice): En lugar de obligar a la IA a realizar 4 consultas manuales sucesivas, la herramienta orquestadora encadena automáticamente: Presupuesto validado $\rightarrow$ Pedido de cliente $\rightarrow$ Factura $\rightarrow$ Validación de la factura.

2. ✏️ Manipulación granular de las líneas (Add / Update / Delete): Soporte completo de la gestión línea por línea en presupuestos, pedidos y facturas (adición de artículos, modificación de cantidades/precios/etiquetas, eliminación de líneas).

3. 🛡️ Modo Seguridad / Solo Lectura Nativo (READ_ONLY=true): Posibilidad de limitar el servidor a solo consulta para entornos de producción sensibles. Todas las solicitudes de escritura (POST, PUT, DELETE) se interceptan y rechazan en el origen.

4. 🔁 Resiliencia y Backoff Exponencial (HTTP 429): Gestión inteligente de los límites de velocidad de la API de Dolibarr: reintenta automáticamente con espera (1s, 2s, 4s) en caso de sobrecarga sin hacer fallar al agente de IA.

5. 🎯 Limpieza y Formateo Optimizados para LLM:

   • Las respuestas JSON brutas de Dolibarr (a menudo repletas de más de 50 campos internos inútiles) se limpian y se resumen en texto claro y legible.

   • Validación estricta previa (correos electrónicos, importes positivos, campos obligatorios) para evitar enviar solicitudes malformadas a Dolibarr.

6. 📄 Generación y Extracción Real de Archivos PDF: Permite ordenar la generación de los PDF reglamentarios y recuperar su contenido codificado en Base64 para el agente de IA.

7. 🌐 Multi-Transporte Nativo (stdio, http, sse, streamable-http): Funciona tanto localmente en ordenador (Claude Desktop, Cursor) como en un microservicio contenedorizado en un servidor en la nube.

🏃 Cómo Lanzar y Ejecutar el Servidor MCP (Run)

1. Preparación del entorno 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

En el archivo .env, configure el acceso a su instancia de 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. Inicio del Servidor MCP

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

Inicio simple en el terminal:

python server.py

Para conectar Claude Desktop, añada la siguiente configuración en su archivo 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. Modo Servidor Remoto http / Streamable HTTP

Para exponer el servidor MCP a través de HTTP (por ejemplo, en un servidor remoto o un contenedor en la nube):

MCP_TRANSPORT=http MCP_PORT=8000 python server.py

El servidor será accesible en http://0.0.0.0:8000.

3. Ejecución con Docker

Mediante Docker Compose (Recomendado)

docker-compose up -d --build

Mediante Docker CLI

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

🧪 Ejecución de las Pruebas Unitarias

La suite de pruebas unitarias valida el comportamiento del cliente y de las herramientas con pytest y el mock HTTP respx (sin ninguna llamada de red real ni modificación en su Dolibarr):

pytest

📁 Arquitectura y Estructura del Proyecto

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