mirror of
https://github.com/latinogino/dolibarr-mcp.git
synced 2026-04-25 19:15:35 +02:00
397 lines
11 KiB
Markdown
397 lines
11 KiB
Markdown
# Dolibarr MCP Server
|
|
|
|
Professional Model Context Protocol (MCP) server for comprehensive Dolibarr ERP integration with full CRUD operations and business intelligence capabilities.
|
|
|
|
[](https://python.org)
|
|
[](LICENSE)
|
|
[](https://modelcontextprotocol.io)
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Automated Setup (Recommended)
|
|
|
|
**For Windows:**
|
|
```bash
|
|
git clone https://github.com/latinogino/dolibarr-mcp.git
|
|
cd dolibarr-mcp
|
|
setup.bat
|
|
```
|
|
|
|
**For Linux/Mac:**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```env
|
|
# 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
|
|
|
|
1. **Enable the API module** in Dolibarr:
|
|
- Go to Home → Setup → Modules
|
|
- Enable "Web Services API REST (developer)"
|
|
|
|
2. **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
|
|
|
|
3. **Test the API**:
|
|
```bash
|
|
curl -X GET "https://your-dolibarr-instance.com/api/index.php/status" \
|
|
-H "DOLAPIKEY: your_api_key_here"
|
|
```
|
|
|
|
## 🏃♂️ Running the Server
|
|
|
|
### Development Mode
|
|
|
|
**Windows:**
|
|
```bash
|
|
venv_dolibarr\Scripts\python.exe -m dolibarr_mcp.dolibarr_mcp_server
|
|
```
|
|
|
|
**Linux/Mac:**
|
|
```bash
|
|
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`
|
|
|
|
```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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
# Install test dependencies
|
|
pip install pytest pytest-asyncio pytest-cov
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Run with coverage
|
|
pytest --cov=src/dolibarr_mcp
|
|
```
|
|
|
|
Test API connection:
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
### Development Setup
|
|
|
|
```bash
|
|
# 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](LICENSE) file for details.
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- [Dolibarr](https://www.dolibarr.org/) - The amazing open-source ERP/CRM
|
|
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
|
|
- [Anthropic](https://www.anthropic.com/) - For the MCP standard
|
|
|
|
## 📞 Support
|
|
|
|
- 📖 [Documentation](https://github.com/latinogino/dolibarr-mcp#readme)
|
|
- 🐛 [Issue Tracker](https://github.com/latinogino/dolibarr-mcp/issues)
|
|
- 💬 [Discussions](https://github.com/latinogino/dolibarr-mcp/discussions)
|
|
|
|
## 🗺️ Roadmap
|
|
|
|
### Phase 1 (Completed) ✅
|
|
- [x] Core MCP server implementation
|
|
- [x] Full CRUD operations for main entities
|
|
- [x] Professional error handling
|
|
- [x] Automated setup scripts
|
|
- [x] Docker support
|
|
- [x] 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**
|