# Odoo-MCP Technical Documentation
## Table of Contents
1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Resources and Tools](#resources-and-tools)
4. [Data Models](#data-models)
5. [Usage Examples](#usage-examples)
6. [Advantages](#advantages)
7. [Configuration](#configuration)
8. [Best Practices](#best-practices)
## Overview
Odoo-MCP is a bridge system that provides a modern interface for interacting with Odoo ERP systems through MCP (Model Context Protocol). It consists of two main components:
1. An XML-RPC client for Odoo communication
2. An MCP server that exposes Odoo functionality through standardized resources and tools
## Architecture
### 1. Odoo Client (`odoo_client.py`)
The foundation layer that handles direct communication with Odoo servers through XML-RPC protocol.
#### Key Features:
- Robust authentication handling
- Automatic protocol detection (HTTP/HTTPS)
- SSL verification options
- Timeout and redirect management
- Proxy support
- Comprehensive error handling
### 2. MCP Server (`server.py`)
The interface layer that exposes Odoo functionality through standardized MCP resources and tools.
#### Components:
- FastMCP server implementation
- Resource definitions
- Tool definitions
- Type-safe Pydantic models
- Application lifecycle management
### 3. Entry Point (`__main__.py`)
Handles server startup and environment configuration.
## Resources and Tools
### MCP Resources
1. **Model Listing**
```
Resource: odoo://models
Description: Lists all available models in the Odoo system
```
2. **Model Information**
```
Resource: odoo://model/{model_name}
Description: Get detailed information about a specific model including fields
```
3. **Record Access**
```
Resource: odoo://record/{model_name}/{record_id}
Description: Get detailed information of a specific record by ID
```
4. **Record Search**
```
Resource: odoo://search/{model_name}/{domain}
Description: Search for records matching the domain
```
### MCP Tools
1. **Method Execution**
```python
Tool: execute_method
Parameters:
- model: str
- method: str
- args: List
- kwargs: Dict[str, Any]
```
2. **Employee Search**
```python
Tool: search_employee
Parameters:
- name: str
- limit: int = 20
```
3. **Holiday Search**
```python
Tool: search_holidays
Parameters:
- start_date: str
- end_date: str
- employee_id: Optional[int]
```
## Data Models
### Search Models
```python
class DomainCondition:
field: str
operator: str
value: Any
class SearchDomain:
conditions: List[DomainCondition]
```
### Response Models
```python
class EmployeeSearchResult:
id: int
name: str
class Holiday:
display_name: str
start_datetime: str
stop_datetime: str
employee_id: List[Union[int, str]]
name: str
state: str
```
## Usage Examples
1. **Basic Model Exploration**
```python
# List all models
response = mcp.get_resource("odoo://models")
# Get information about a specific model
response = mcp.get_resource("odoo://model/res.partner")
```
2. **Record Search**
```python
# Search for partners
domain = json.dumps([["is_company", "=", True]])
response = mcp.get_resource(f"odoo://search/res.partner/{domain}")
```
3. **Employee Management**
```python
# Search for employees
result = mcp.tools.search_employee(name="John", limit=10)
# Check employee holidays
holidays = mcp.tools.search_holidays(
start_date="2024-01-01",
end_date="2024-12-31",
employee_id=123
)
```
4. **Custom Method Execution**
```python
result = mcp.tools.execute_method(
model="sale.order",
method="action_confirm",
args=[order_id]
)
```
## Advantages
1. **Integration Benefits**
- Standardized interface to Odoo
- Type-safe operations
- Modern async-compatible design
- Robust error handling
- Comprehensive logging
2. **Development Benefits**
- Clear separation of concerns
- Modular architecture
- Easy to extend
- Well-documented interfaces
- Type hints throughout
3. **Operational Benefits**
- Configuration through environment variables
- Flexible deployment options
- Built-in monitoring capabilities
- Production-ready error handling
- Comprehensive logging
4. **Security Benefits**
- SSL verification options
- Secure password handling
- Session management
- Proxy support
- Access control
## Configuration
### Environment Variables
```bash
ODOO_URL=https://your-odoo-server
ODOO_DB=your-database
ODOO_USERNAME=your-username
ODOO_PASSWORD=your-password
ODOO_TIMEOUT=30
ODOO_VERIFY_SSL=1
```
### Configuration Files
Can be placed in:
- `./odoo_config.json`
- `~/.config/odoo/config.json`
- `~/.odoo_config.json`
Example configuration file format:
```json
{
"url": "https://your-odoo-server",
"db": "your-database",
"username": "your-username",
"password": "your-password",
"timeout": 30,
"verify_ssl": true
}
```
## Best Practices
### 1. Error Handling
- Always check response status
- Handle timeouts appropriately
- Implement retry logic for transient failures
- Log errors comprehensively
### 2. Performance
- Use search_read instead of separate search and read
- Implement pagination for large datasets
- Specify required fields explicitly
- Use appropriate timeout values
### 3. Security
- Use HTTPS when possible
- Implement proper credential management
- Validate input data
- Handle sensitive information carefully
### 4. Maintenance
- Monitor server health
- Implement proper logging
- Keep configuration updated
- Regular security updates
## Common Use Cases
### 1. Data Synchronization
```python
# Example: Sync contacts from Odoo to another system
contacts = client.search_read(
"res.partner",
domain=[("write_date", ">=", last_sync_date)],
fields=["name", "email", "phone"]
)
```
### 2. Business Process Automation
```python
# Example: Confirm multiple sales orders
order_ids = [1, 2, 3]
for order_id in order_ids:
mcp.tools.execute_method(
model="sale.order",
method="action_confirm",
args=[order_id]
)
```
### 3. Reporting
```python
# Example: Get sales statistics
sales_data = client.search_read(
"sale.order",
domain=[("date_order", ">=", start_date)],
fields=["name", "amount_total", "state"]
)
```
### 4. Integration with External Systems
```python
# Example: Create products from external data
for product in external_products:
mcp.tools.execute_method(
model="product.template",
method="create",
args=[{
"name": product["name"],
"list_price": product["price"],
"type": "product"
}]
)
```
## Troubleshooting
### Common Issues and Solutions
1. **Connection Issues**
```python
# Check server availability
try:
models = client.get_models()
except Exception as e:
print(f"Connection failed: {e}")
```
2. **Authentication Problems**
- Verify credentials in configuration
- Check database name
- Ensure user has appropriate permissions
3. **Performance Issues**
- Use pagination for large datasets
- Implement caching where appropriate
- Monitor query execution time
4. **SSL Certificate Issues**
- Verify SSL certificate validity
- Configure verify_ssl appropriately
- Use proper certificate authorities
## Contributing
### Development Setup
1. Clone the repository
2. Install dependencies
3. Configure environment variables
4. Run tests
### Testing
```bash
# Run unit tests
python -m pytest tests/
# Run integration tests
python -m pytest tests/integration/
```
### Code Style
- Follow PEP 8 guidelines
- Use type hints
- Document all public interfaces
- Write comprehensive tests
## License
This project is licensed under the MIT License - see the LICENSE file for details.
