> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloleo.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Odoo Integration
> Connect HelloLeo to your Odoo ERP system
Connect HelloLeo to your Odoo instance to read and write data directly from your ERP system.
## Quickstart
Click **Odoo** on the main page and enter your credentials.
Ask Leo to explore your Odoo: *"Check my Odoo and tell me what models and data I have."*
Describe what you want: *"Create a customer portal showing their orders and invoices."*
Your webapp is directly connected to your Odoo. Create dashboards, portals, internal tools—anything you need.
## Setup
1. Go to **Project Settings** → **Project Integrations**
2. Select **Odoo** from the list
3. Enter your Odoo credentials:
* **Odoo Instance URL** - Your Odoo instance URL (e.g., `https://your-instance.odoo.com`)
* **Database Name** - Your Odoo database name
* **Username** - Your Odoo username
* **Password/API Key** - Your Odoo password or API key
* **User ID (UID)** - Click "Authenticate" to automatically get your UID
4. Test the connection
5. Start using Odoo in your prompts
## How It Works
HelloLeo uses the Odoo MCP (Model Context Protocol) to interact with your Odoo instance. Your credentials are encrypted and stored securely on the backend.
## HelloLeo Middleware
When HelloLeo creates a frontend application connected to Odoo, all API requests are automatically routed through the **HelloLeo Middleware**. This middleware acts as a secure proxy between your frontend and Odoo, providing several important benefits:
### How It Works
1. **Frontend makes request** - Your HelloLeo-generated frontend sends API requests to the HelloLeo Middleware
2. **Middleware forwards request** - The middleware forwards the request to Odoo using your stored API credentials
3. **Odoo responds** - Odoo processes the request and sends a response back through the middleware
4. **Frontend receives data** - The response is returned to your frontend application
### Benefits
* **No CORS Issues** - Requests work immediately without CORS configuration. The middleware handles all cross-origin requests seamlessly.
* **Secure API Keys** - Your Odoo API keys are encrypted and stored securely on the backend. They're never exposed to the frontend or end users.
* **Automatic Authentication** - The middleware automatically includes your Odoo credentials in every request, so you don't need to manage authentication in your frontend code.
* **Permission Management** - (Coming soon) You'll be able to manage permissions and access control through the middleware, giving you fine-grained control over what data each user can access.
### Technical Details
The middleware:
* Encrypts and stores your Odoo credentials securely
* Handles Odoo's JSON-RPC protocol automatically
* Manages session authentication and MFA
* Provides a consistent API interface for your frontend
* Logs all requests for debugging (visible in Network Monitor)
You don't need to configure anything - when you connect Odoo in HelloLeo, the middleware is automatically set up for your project.
## MCP Operations
### `execute_method`
A generic tool that executes any method on any Odoo model.
**Parameters:**
* `model` (required): The Odoo model name (e.g., `'res.partner'`, `'sale.order'`, `'product.product'`)
* `method` (required): The method name to execute (e.g., `'search'`, `'read'`, `'create'`, `'write'`, `'unlink'`, `'search_read'`, `'search_count'`)
* `args` (optional): List of positional arguments
* `kwargs` (optional): Dictionary of keyword arguments
**Returns:**
* `success`: Boolean indicating success/failure
* `result`: The method result (if successful)
* `error`: Error message (if failed)
**Special handling:**
* Domain normalization for search methods (`search`, `search_count`, `'search_read'`)
* Supports multiple domain formats (lists, dictionaries with conditions, JSON strings)
* Handles Odoo domain operators (`&`, `|`, `!`)
## Common Methods
### Search Records
* `search`: Find records by domain
* `search_read`: Search and read in one call
* `search_count`: Count records matching domain
### Read Records
* `read`: Get record details by IDs
### Create Records
* `create`: Create new records
### Update Records
* `write`: Update existing records
### Delete Records
* `unlink`: Delete records
### Custom Methods
* Any custom method defined on the model
## Example Usage
### Search and Display Products
```
Show all products from Odoo where quantity is greater than 0.
Display product name, price, and available quantity.
```
### Create a Customer
```
Create a new customer in Odoo with name "Acme Corp",
email "contact@acme.com", and phone "555-1234".
```
### Update an Order
```
Update order SO001 in Odoo to set the status to "confirmed".
```
### Search Partners
```
Find all companies in Odoo and show their name, email, and phone.
```
## Example MCP Command
```
mcp odoo execute_method {"model":"res.partner","method":"search_read","args":[[["is_company","=",true]]],"kwargs":{"fields":["name","email","phone"]}}
```
## Authentication
### Admin Authentication (Setup)
When configuring the Odoo integration in HelloLeo, you authenticate using an admin or technical user account. This account is used by the HelloLeo Middleware to make API calls on behalf of your application.
The integration supports Odoo's Multi-Factor Authentication (MFA). When you authenticate, if MFA is enabled, you'll be prompted to enter your MFA code.
**Important:** The credentials you provide during setup are encrypted and stored securely. They're used by the middleware to authenticate all API requests, but are never exposed to your frontend code or end users.
### Portal User Authentication
When building customer portals or frontend applications with HelloLeo, you can implement portal user authentication so that end users (customers, vendors, etc.) log in with their own Odoo portal accounts.
#### How Portal Authentication Works
1. **Portal User Login** - End users log in using their Odoo portal credentials (email/password) through your HelloLeo-generated frontend
2. **Session Creation** - The frontend authenticates with Odoo's `/web/session/authenticate` endpoint through the HelloLeo Middleware
3. **Session Management** - Odoo returns a session ID that identifies the portal user
4. **Data Access** - All subsequent API requests use this session to access data according to the portal user's permissions in Odoo
#### Implementing Portal Authentication
When building a portal, ask Leo to:
```
Create a login page where portal users can authenticate with their
Odoo credentials. After login, store the session and use it for
all Odoo API calls. Show only data the portal user has access to
based on their Odoo permissions.
```
#### Portal User Permissions
Portal users in Odoo have limited access based on:
* **Record Rules** - Odoo's record-level security rules
* **Access Rights** - Model-level read/write permissions
* **Portal Groups** - Portal user group membership
The HelloLeo Middleware respects all Odoo security rules, so portal users can only access data they're authorized to see in Odoo.
#### Security Considerations
* Portal users authenticate directly with Odoo, not with HelloLeo
* Session data is managed securely through the middleware
* All Odoo security rules and permissions are enforced
* API keys used by the middleware are separate from portal user sessions
## Best Practices
* **Be specific about models** - Always mention which Odoo model you're working with (e.g., "products", "customers", "orders")
* **Specify fields** - Tell Leo which fields to display or update
* **Use domain filters** - Describe what records you want to find (e.g., "active products", "confirmed orders")
* **Mention the integration** - Always say "from Odoo" or "to Odoo" so Leo knows which integration to use
## Troubleshooting
### Connection Errors
#### "Database does not exist"
This error means the database name you entered doesn't match the actual database on your Odoo server.
**How to find your database name:**
1. **Odoo.com hosted instances**: The database name is usually your subdomain (e.g., for `https://mycompany.odoo.com`, the database is `mycompany`)
2. **Self-hosted Odoo**: Go to `https://your-odoo-url/web/database/manager` to see available databases
3. **Ask your administrator**: Your Odoo administrator can provide the exact database name
**Odoo.sh users:**
On Odoo.sh, the technical database name is different from your subdomain. For example, your URL might be `https://mycompany.odoo.com`, but the actual database name could be something like `mycompany-main-12345678`. To find your technical database name:
* Enable debug mode (add `?debug=1` to your URL), then look at the top-right corner of the screen — your database name will be displayed there. If the name is truncated with `...`, press F12 in your browser, inspect the element, and read the full value.
* Or install the [Odoo Toolbox](https://chromewebstore.google.com/detail/odoo-debug/hmdmhilocobgohohpdpolmibjklfgkbi) browser extension, click the icon at the bottom-right, then click "Database" to copy the full name.
**Common mistakes:**
* Using the full URL instead of just the database name
* Adding extra characters or spaces
* Case sensitivity issues (database names are case-sensitive)
#### "Could not connect to Odoo instance"
**Possible causes:**
* **Wrong URL format**: Use `https://your-instance.odoo.com` without `/odoo` or `/web` at the end
* **Network issues**: Check if your Odoo instance is accessible from your network
* **Firewall blocking**: Some Odoo instances restrict external API access
**URL format examples:**
* ✅ Correct: `https://mycompany.odoo.com`
* ❌ Wrong: `https://mycompany.odoo.com/odoo`
* ❌ Wrong: `https://mycompany.odoo.com/web`
#### "Invalid credentials"
* Verify your username (usually your email address)
* Check your password or API key
* Ensure the user account is active in Odoo
* If using an API key, make sure it hasn't expired
#### "Access Denied" or Permission Errors
* Your Odoo user may not have API access enabled
* Check with your Odoo administrator to ensure external API access is allowed
* Some Odoo editions (like Odoo Online free tier) may have API restrictions
### Authentication Issues
* **Check credentials** - Verify your URL, database name, username, and password are correct
* **MFA enabled** - If MFA is enabled, make sure to complete the MFA verification
* **UID missing** - Click "Authenticate" to get your User ID
### Data Not Showing
* **Check model name** - Ensure you're using the correct Odoo model name
* **Verify permissions** - Make sure your user has access to the model and records
* **Check domain** - Review your search criteria
### Getting Help
If you're still having issues:
1. Check your Odoo server logs for more detailed error messages
2. Contact your Odoo administrator to verify API access is enabled
3. Reach out to HelloLeo support with the exact error message you're seeing
Learn how to use integrations effectively
Debug Odoo API calls