Odoo MCP Connection¶

Overview¶

The Odoo Model Context Protocol (MCP) server enables natural language interaction with Odoo ERP systems (versions 17, 18, 19) through WorkBuddy. This connection allows AI assistants to perform basic Odoo operations such as querying records, creating sales orders, managing contacts, and more via natural language commands.

Key Features: - Natural language access to Odoo data and operations - Support for Odoo 17/18 (XML-RPC) and Odoo 19+ (JSON‑2) - Integration with WorkBuddy's MCP framework - Secure credential management via environment variables - Configurable timeouts and retry logic

Prerequisites¶

Odoo Instance: A running Odoo instance (on-premise or cloud) with API access enabled
API User: An Odoo user with appropriate permissions and an API key
Python 3.8+: Required for the Odoo MCP server package
WorkBuddy: Desktop version with MCP support enabled

Installation¶

1. Install the Odoo MCP Package¶

pip install odoo-mcp

Verify the installation:

python -c "import odoo_mcp.server; print('Module loaded successfully')"

2. Configuration Template¶

Create a configuration template to document the required settings:

{
  "url": "http://localhost:8069",
  "db": "your_database_name",
  "username": "api_user@yourcompany.com",
  "apiKey": "your_api_key_from_odoo_preferences",
  "timeout": 60,
  "maxRetries": 3,
  "pollInterval": 60,
  "logLevel": "INFO",
  "webhookPort": 8070,
  "webhookSecret": ""
}

Save this as odoo_config.json in your workspace.

3. Register with WorkBuddy¶

Update your WorkBuddy MCP configuration (~/.workbuddy/mcp.json):

{
  "mcpServers": {
    "odoo": {
      "command": "python",
      "args": ["-m", "odoo_mcp.server"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "your_database_name",
        "ODOO_USERNAME": "api_user@yourcompany.com",
        "ODOO_API_KEY": "your_api_key_from_odoo_preferences",
        "ODOO_TIMEOUT": "60",
        "ODOO_MAX_RETRIES": "3",
        "ODOO_POLL_INTERVAL": "60",
        "ODOO_LOG_LEVEL": "INFO",
        "ODOO_WEBHOOK_PORT": "8070",
        "ODOO_WEBHOOK_SECRET": ""
      }
    }
  }
}

4. Set Environment Variables¶

Replace the placeholder values in the env section with your actual Odoo credentials:

Variable	Description	Example
`ODOO_URL`	Odoo instance URL	`https://yourcompany.odoo.com`
`ODOO_DB`	Database name	`yourcompany_prod`
`ODOO_USERNAME`	API user email	`api_user@yourcompany.com`
`ODOO_API_KEY`	API key from Odoo preferences	`a1b2c3d4e5f6...`
`ODOO_TIMEOUT`	Request timeout in seconds	`60`
`ODOO_MAX_RETRIES`	Maximum retry attempts	`3`
`ODOO_POLL_INTERVAL`	Polling interval for async operations	`60`
`ODOO_LOG_LEVEL`	Log verbosity	`INFO`
`ODOO_WEBHOOK_PORT`	Webhook listener port (optional)	`8070`
`ODOO_WEBHOOK_SECRET`	Webhook secret (optional)	`your_secret`

Usage¶

Basic Commands¶

Once configured, you can interact with Odoo using natural language through WorkBuddy:

Query records: "Show me the last 10 sales orders"
Create records: "Create a new contact for John Doe at ACME Corp"
Update records: "Mark sales order SO001 as confirmed"
Report data: "What's our total revenue this month?"

Example Workflows¶

1. Query Sales Orders¶

User: "List the last 5 sales orders with amounts over $1000"
Assistant: (Uses MCP to query Odoo and return formatted results)

2. Create a Contact¶

User: "Add a new customer contact: Jane Smith, jane@example.com, phone 555-0123"
Assistant: (Creates a new partner record in Odoo via MCP)

3. Check Inventory¶

User: "What's the current stock level for product iPhone 15?"
Assistant: (Queries Odoo inventory and returns available quantity)

Supported Odoo Models¶

The MCP server provides access to common Odoo models:

Model	Description	Key Operations
`res.partner`	Contacts/Customers	Create, read, update, search
`sale.order`	Sales Orders	Create, confirm, invoice, cancel
`account.move`	Invoices	Create, post, reconcile
`product.product`	Products	Read, update stock
`stock.picking`	Transfers	Confirm, process, validate
`project.task`	Tasks	Create, assign, update status
`hr.employee`	Employees	Read basic info

Troubleshooting¶

Common Issues¶

Connection Refused
Verify ODOO_URL points to a running Odoo instance
Check firewall/network access
Ensure Odoo XML-RPC/JSON‑2 interface is enabled
Authentication Failed
Confirm ODOO_DB, ODOO_USERNAME, and ODOO_API_KEY are correct
Verify the user has API access permissions in Odoo
Check if the API key was generated from User Preferences
Module Import Error
```
python -c "import odoo_mcp.server"
```
Reinstall the package: pip install --upgrade odoo-mcp
Check Python version compatibility
WorkBuddy Doesn't Recognize MCP
Restart WorkBuddy after updating mcp.json
Check WorkBuddy logs for MCP initialization errors
Verify mcp.json syntax is valid JSON

Logs and Debugging¶

Set ODOO_LOG_LEVEL to DEBUG for detailed logs:

"env": {
  "ODOO_LOG_LEVEL": "DEBUG"
}

Logs will appear in WorkBuddy's console output or log files.

Security Considerations¶

API Key Management
Store API keys in environment variables, not in version control
Use separate API users for different applications
Rotate API keys periodically
Network Security
Use HTTPS for production Odoo instances
Restrict API access to trusted IP ranges if possible
Consider VPN/private network for on-premise deployments
Permission Scoping
Grant minimum necessary permissions to the API user
Regularly audit user permissions in Odoo

Maintenance¶

Version Updates¶

Check for package updates:

pip list --outdated | grep odoo-mcp

Update when available:

pip install --upgrade odoo-mcp

Configuration Migration¶

When migrating to a new environment: 1. Update environment variables in mcp.json 2. Test connection with the new credentials 3. Update any related documentation

Last Updated: 2026-05-19
Maintainer: WorkBuddy Automation
Status: Active ✅