Professional Model Context Protocol (MCP) server for comprehensive Dolibarr ERP integration with full CRUD operations and business intelligence capabilities.

🚀 Quick Start

Automated Setup (Recommended)

For Windows:

git clone https://github.com/latinogino/dolibarr-mcp.git
cd dolibarr-mcp
setup.bat

For Linux/Mac:

git clone https://github.com/latinogino/dolibarr-mcp.git
cd dolibarr-mcp
chmod +x setup.sh
./setup.sh

This will:

Create a virtual environment (venv_dolibarr)
Install all dependencies
Create a .env configuration file
Test the installation

Manual Setup

git clone https://github.com/latinogino/dolibarr-mcp.git
cd dolibarr-mcp

# Create virtual environment
python -m venv venv_dolibarr

# Activate virtual environment
# Windows:
venv_dolibarr\Scripts\activate
# Linux/Mac:
source venv_dolibarr/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -e .

⚙️ Configuration

Edit the .env file with your Dolibarr instance details:

# Dolibarr API Configuration
DOLIBARR_URL=https://your-dolibarr-instance.com/api/index.php
DOLIBARR_API_KEY=your_dolibarr_api_key_here

# Logging Configuration
LOG_LEVEL=INFO

Dolibarr API Setup

Enable the API module in Dolibarr:
- Go to Home → Setup → Modules
- Enable "Web Services API REST (developer)"
Create an API key:
- Go to Home → Setup → API/Web services
- Create a new API key for your user
- Ensure the user has appropriate permissions

Test the API:

curl -X GET "https://your-dolibarr-instance.com/api/index.php/status" \
  -H "DOLAPIKEY: your_api_key_here"

🏃‍♂️ Running the Server

Development Mode

Windows:

venv_dolibarr\Scripts\python.exe -m dolibarr_mcp.dolibarr_mcp_server

Linux/Mac:

venv_dolibarr/bin/python -m dolibarr_mcp.dolibarr_mcp_server

With Claude Desktop

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dolibarr-mcp": {
      "command": "C:\\path\\to\\your\\dolibarr-mcp\\venv_dolibarr\\Scripts\\python.exe",
      "args": ["-m", "dolibarr_mcp.dolibarr_mcp_server"],
      "cwd": "C:\\path\\to\\your\\dolibarr-mcp",
      "env": {
        "DOLIBARR_URL": "https://your-dolibarr-instance.com/api/index.php",
        "DOLIBARR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Docker (Alternative)

docker-compose up

🚀 Features

Complete ERP Management

Customer/Third Party Management: Full CRUD operations for customers and suppliers
Product Catalog: Comprehensive product management with inventory tracking
Invoice Management: Create, update, and track invoices with line items
Order Processing: Complete order lifecycle management
Contact Management: Maintain detailed contact records
User Administration: User account and permissions management

Professional Grade

Asynchronous Operations: High-performance async/await architecture
Error Handling: Comprehensive error handling with detailed logging
Type Safety: Full type hints with Pydantic validation
CLI Interface: Professional command-line tools for testing and management
Raw API Access: Direct access to any Dolibarr API endpoint

MCP Integration

Tool-based Architecture: Each operation exposed as an MCP tool
Schema Validation: Proper input/output schema validation
Response Formatting: Structured JSON responses
Error Propagation: Meaningful error messages and status codes

📋 Prerequisites

Python 3.8 or higher
Dolibarr instance with API enabled
Dolibarr API key with appropriate permissions

🛠️ Available Tools

The server exposes comprehensive tools for Dolibarr management:

System Tools

test_connection - Test API connectivity
get_status - Get system status and version

Customer Management

get_customers - List customers/third parties
get_customer_by_id - Get specific customer details
create_customer - Create new customer
update_customer - Update existing customer
delete_customer - Delete customer

Product Management

get_products - List products
get_product_by_id - Get specific product details
create_product - Create new product
update_product - Update existing product
delete_product - Delete product

Invoice Management

get_invoices - List invoices
get_invoice_by_id - Get specific invoice details
create_invoice - Create new invoice with line items
update_invoice - Update existing invoice
delete_invoice - Delete invoice

Order Management

get_orders - List orders
get_order_by_id - Get specific order details
create_order - Create new order
update_order - Update existing order
delete_order - Delete order

Contact Management

get_contacts - List contacts
get_contact_by_id - Get specific contact details
create_contact - Create new contact
update_contact - Update existing contact
delete_contact - Delete contact

User Management

get_users - List users
get_user_by_id - Get specific user details
create_user - Create new user
update_user - Update existing user
delete_user - Delete user

Raw API Access

dolibarr_raw_api - Make direct API calls to any endpoint

💻 Programmatic Usage

import asyncio
from dolibarr_mcp import Config, DolibarrClient

async def main():
    config = Config.from_env()
    
    async with DolibarrClient(config) as client:
        # Get customers
        customers = await client.get_customers(limit=10)
        print(f"Found {len(customers)} customers")
        
        # Create a new customer
        new_customer = await client.create_customer(
            name="Test Company",
            email="test@company.com",
            phone="+1-555-0123"
        )
        print(f"Created customer: {new_customer}")
        
        # Get products
        products = await client.get_products(limit=5)
        print(f"Found {len(products)} products")

asyncio.run(main())

🧪 Testing

Run the test suite:

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov

# Run tests
pytest

# Run with coverage
pytest --cov=src/dolibarr_mcp

Test API connection:

# Windows:
venv_dolibarr\Scripts\python.exe -c "from dolibarr_mcp import Config, DolibarrClient; import asyncio; asyncio.run(DolibarrClient(Config()).get_status())"

# Linux/Mac:
venv_dolibarr/bin/python -c "from dolibarr_mcp import Config, DolibarrClient; import asyncio; asyncio.run(DolibarrClient(Config()).get_status())"

🏗️ Project Structure

dolibarr-mcp/
├── src/dolibarr_mcp/
│   ├── __init__.py              # Package exports
│   ├── config.py                # Configuration management
│   ├── cli.py                   # Command line interface
│   ├── dolibarr_client.py       # API client implementation
│   └── dolibarr_mcp_server.py   # MCP server implementation
├── tests/                       # Test suite
├── api/                         # API documentation
├── setup.py                     # Development setup script
├── setup.bat                    # Windows setup script
├── setup.sh                     # Linux/Mac setup script
├── pyproject.toml              # Project configuration
├── requirements.txt            # Dependencies
├── Dockerfile                  # Docker configuration
├── docker-compose.yml          # Docker Compose configuration
└── README.md                   # This file

🐳 Docker Support

Build and run with Docker:

# Build image
docker build -t dolibarr-mcp .

# Run with docker-compose
docker-compose up

# Run container directly
docker run -p 8080:8080 --env-file .env dolibarr-mcp

🔧 Troubleshooting

Common Issues

1. Virtual Environment Not Found

# Make sure you created the virtual environment:
python -m venv venv_dolibarr

# And use the correct path in Claude Desktop config

2. API Connection Failed

# Test your API key and URL:
curl -X GET "https://your-dolibarr-instance.com/api/index.php/status" \
  -H "DOLAPIKEY: your_api_key_here"

3. Module Import Errors

# Install in development mode:
pip install -e .

4. Permission Errors

Ensure your Dolibarr user has API access
Check that the API module is enabled
Verify user permissions for the operations you want to perform

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/yourusername/dolibarr-mcp.git
cd dolibarr-mcp

# Run setup script
python setup.py

# Install development dependencies
pip install pytest pytest-asyncio pytest-cov

# Run tests
pytest

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Dolibarr - The amazing open-source ERP/CRM
Model Context Protocol - The protocol specification
Anthropic - For the MCP standard

📞 Support

🗺️ Roadmap

Phase 1 (Completed) ✅

Core MCP server implementation
Full CRUD operations for main entities
Professional error handling
Automated setup scripts
Docker support
Comprehensive documentation

Phase 2 (Next)

Advanced filtering and search
Webhook support
Performance optimization
Extended API coverage
Unit tests

Phase 3 (Future)

Web UI for management
Multi-instance support
Caching layer
Metrics and monitoring
Plugin system

Built with ❤️ for the Dolibarr community