🚀 mcp-dolibarr

Высокопроизводительный и безопасный MCP-сервер (Model Context Protocol) на базе FastMCP, позволяющий любому ИИ-ассистенту (Claude Desktop, Cursor, AI Agents) нативно взаимодействовать с ERP/CRM Dolibarr через его официальный REST API.

✨ Основные возможности

MCP-сервер покрывает все потребности управления предприятием в Dolibarr с помощью более 30 специализированных инструментов, распределённых по 12 модулям:

• 🏢 Контрагенты и компании (tools/thirdparties.py): список, полнотекстовый поиск по названию, детальный просмотр по ID, создание и частичное обновление карточек клиентов/потенциальных клиентов.

• 👤 Контакты и исполнители (tools/contacts.py): список и создание контактов (физических лиц), привязанных к компаниям.

• 📦 Товары и услуги (tools/products.py): полный каталог товаров и услуг, поиск по артикулу, создание, обновление и управление ценами без НДС / ставками НДС.

• 📄 Сметы и коммерческие предложения (tools/proposals.py): создание многострочных смет, валидация, обновление/удаление строк и автоматическая конвертация.

• 🛒 Заказы клиентов (tools/orders.py): создание заказов на основе подтверждённого коммерческого предложения, просмотр и точная настройка строк заказа.

• 💳 Счета и платежи (tools/invoices.py): создание счетов из заказа или напрямую, финальная валидация и управление строками счёта.

• 📊 Складские остатки по складам (tools/stocks.py): мгновенный просмотр фактических остатков товара по каждому складу.

• 📁 Проекты (tools/projects.py): создание, просмотр и привязка проектов к карточкам клиентов.

• 📜 Договоры (tools/contracts.py): отслеживание сервисных договоров и создание для контрагента.

• 🛠️ Карточки вмешательств (tools/interventions.py): управление карточками технических выездов на объект.

• 📑 Документы и PDF (tools/documents.py): автоматическая генерация официальных PDF (шаблоны Azur, Crabe и т.д.) и загрузка с кодировкой Base64.

• 🔌 Прямой REST API (запасной режим) (tools/raw.py): инструмент call_dolibarr_api, позволяющий напрямую обращаться к любому маршруту REST Dolibarr, не охваченному специализированным инструментом.

Related MCP server: MCP Server for Odoo

🌟 Что mcp-dolibarr даёт дополнительно по сравнению с другими MCP-серверами

В отличие от базовых или универсальных MCP-шлюзов, этот сервер обеспечивает решающую добавленную ценность:

1. 🔄 Сложная оркестрация за один вызов (convert_proposal_to_invoice): Вместо того чтобы заставлять ИИ выполнять 4 последовательных ручных запроса, оркестратор автоматически выполняет цепочку: Подтверждённое коммерческое предложение $\rightarrow$ Заказ клиента $\rightarrow$ Счёт $\rightarrow$ Валидация счёта.

2. ✏️ Детальное управление строками (Add / Update / Delete): Полная поддержка построчного управления в коммерческих предложениях, заказах и счетах (добавление позиций, изменение количеств/цен/наименований, удаление строк).

3. 🛡️ Встроенный режим безопасности / только чтение (READ_ONLY=true): Возможность ограничить сервер режимом только для просмотра для чувствительных производственных сред. Все запросы на запись (POST, PUT, DELETE) перехватываются и отклоняются на корню.

4. 🔁 Устойчивость и экспоненциальный backoff (HTTP 429): Интеллектуальное управление лимитами скорости API Dolibarr: автоматические повторные попытки с паузой (1s, 2s, 4s) при перегрузке, не приводящие к сбою ИИ-агента.

5. 🎯 Очистка и форматирование, оптимизированные для LLM:

   • Сырые JSON-ответы Dolibarr (часто переполненные +50 ненужными внутренними полями) очищаются и сводятся в понятный читаемый текст.

   • Строгая предварительная валидация (email, положительные суммы, обязательные поля) для предотвращения отправки в Dolibarr некорректных запросов.

6. 📄 Реальная генерация и извлечение PDF-файлов: Позволяет заказать генерацию регламентных PDF и получить их содержимое в кодировке Base64 для ИИ-агента.

7. 🌐 Нативная поддержка нескольких транспортов (stdio, http, sse, streamable-http): Работает как локально на компьютере (Claude Desktop, Cursor), так и в виде контейнеризованного микросервиса на облачном сервере.

🏃 Запуск и выполнение MCP-сервера (Run)

1. Подготовка локального окружения

# 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

В файле .env настройте доступ к вашему экземпляру 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. Запуск MCP-сервера

A. Локальный режим stdio (Claude Desktop / Cursor / VS Code)

Простой запуск в терминале:

python server.py

Для подключения Claude Desktop добавьте следующую конфигурацию в ваш файл 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. Удалённый серверный режим http / Streamable HTTP

Чтобы опубликовать MCP-сервер через HTTP (например, на удалённом сервере или в облачном контейнере):

MCP_TRANSPORT=http MCP_PORT=8000 python server.py

Сервер будет доступен по адресу http://0.0.0.0:8000.

3. Запуск с помощью Docker

Через Docker Compose (рекомендуется)

docker-compose up -d --build

Через Docker CLI

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

🧪 Запуск модульных тестов

Набор модульных тестов проверяет поведение клиента и инструментов с помощью pytest и HTTP-мока respx (без реальных сетевых вызовов и изменений в вашем Dolibarr):

pytest

📁 Архитектура и структура проекта

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