An MCP server that enables AI assistants like Claude to interact with Odoo ERP systems. Access business data, search records, and work with Odoo through natural language.
- 🔍 Search and retrieve any Odoo record (customers, products, invoices, etc.)
- 📊 Browse multiple records and get formatted summaries
- 🔢 Count records matching specific criteria
- 📋 Inspect model fields to understand data structure
- 🔐 Secure access with API key or username/password authentication
- 🎯 Smart pagination for large datasets
- 💬 LLM-optimized output with hierarchical text formatting
- Python 3.10 or higher
- Access to an Odoo instance (version 18.0+)
- The Odoo MCP module installed on your Odoo server
- An API key generated in Odoo (Settings > Users > API Keys)
Add this configuration to your MCP settings:
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"odoo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}Cursor
Add to ~/.cursor/mcp_settings.json:
{
"mcpServers": {
"odoo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}VS Code (with GitHub Copilot)
Add to your VS Code settings (~/.vscode/mcp_settings.json or workspace settings):
{
"github.copilot.chat.mcpServers": {
"odoo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}Zed
Add to ~/.config/zed/settings.json:
{
"context_servers": {
"odoo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}Using pip
# Install globally
pip install mcp-server-odoo
# Or use pipx for isolated environment
pipx install mcp-server-odooThen use mcp-server-odoo as the command in your MCP configuration.
From source
git clone https://github.com/ivnvxd/mcp-server-odoo.git
cd mcp-server-odoo
pip install -e .Then use the full path to the package in your MCP configuration.
The server requires the following environment variables:
| Variable | Required | Description | Example |
|---|---|---|---|
ODOO_URL |
Yes | Your Odoo instance URL | https://mycompany.odoo.com |
ODOO_API_KEY |
Yes* | API key for authentication | 0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd |
ODOO_USER |
Yes* | Username (if not using API key) | admin |
ODOO_PASSWORD |
Yes* | Password (if not using API key) | admin |
ODOO_DB |
No | Database name (auto-detected if not set) | mycompany |
*Either ODOO_API_KEY or both ODOO_USER and ODOO_PASSWORD are required.
-
Install the MCP module:
- Download the mcp_server module
- Install it in your Odoo instance
- Navigate to Settings > MCP Server
-
Enable models for MCP access:
- Go to Settings > MCP Server > Enabled Models
- Add models you want to access (e.g., res.partner, product.product)
- Configure permissions (read, write, create, delete) per model
-
Generate an API key:
- Go to Settings > Users & Companies > Users
- Select your user
- Under the "API Keys" tab, create a new key
- Copy the key for your MCP configuration
Once configured, you can ask Claude:
- "Show me all customers from Spain"
- "Find products with stock below 10 units"
- "List today's sales orders over $1000"
- "Search for unpaid invoices from last month"
- "Count how many active employees we have"
- "Show me the contact information for Microsoft"
Search for records in any Odoo model with filters.
{
"model": "res.partner",
"domain": [["is_company", "=", true], ["country_id.code", "=", "ES"]],
"fields": ["name", "email", "phone"],
"limit": 10
}Field Selection Options:
- Omit
fieldsor set tonull: Returns smart selection of common fields - Specify field list: Returns only those specific fields
- Use
["__all__"]: Returns all fields (use with caution)
Retrieve a specific record by ID.
{
"model": "res.partner",
"record_id": 42,
"fields": ["name", "email", "street", "city"]
}Field Selection Options:
- Omit
fieldsor set tonull: Returns smart selection of common fields with metadata - Specify field list: Returns only those specific fields
- Use
["__all__"]: Returns all fields without metadata
List all models enabled for MCP access.
{}Create a new record in Odoo.
{
"model": "res.partner",
"values": {
"name": "New Customer",
"email": "customer@example.com",
"is_company": true
}
}Update an existing record.
{
"model": "res.partner",
"record_id": 42,
"values": {
"phone": "+1234567890",
"website": "https://example.com"
}
}Delete a record from Odoo.
{
"model": "res.partner",
"record_id": 42
}The server also provides direct access to Odoo data through resource URIs:
odoo://res.partner/record/1- Get partner with ID 1odoo://product.product/search?domain=[["qty_available",">",0]]- Search products in stockodoo://sale.order/browse?ids=1,2,3- Browse multiple sales ordersodoo://res.partner/count?domain=[["customer_rank",">",0]]- Count customersodoo://product.product/fields- List available fields for products
- Always use HTTPS in production environments
- Keep your API keys secure and rotate them regularly
- Configure model access carefully - only enable necessary models
- The MCP module respects Odoo's built-in access rights and record rules
- Each API key is linked to a specific user with their permissions
Connection Issues
If you're getting connection errors:
- Verify your Odoo URL is correct and accessible
- Check that the MCP module is installed: visit
https://your-odoo.com/mcp/health - Ensure your firewall allows connections to Odoo
Authentication Errors
If authentication fails:
- Verify your API key is active in Odoo
- Check that the user has appropriate permissions
- Try regenerating the API key
- For username/password auth, ensure 2FA is not enabled
If you can't access certain models:
- Go to Settings > MCP Server > Enabled Models in Odoo
- Ensure the model is in the list and has appropriate permissions
- Check that your user has access to that model in Odoo's security settings
Debug Mode
Enable debug logging for more information:
{
"env": {
"ODOO_URL": "https://your-odoo.com",
"ODOO_API_KEY": "your-key",
"ODOO_MCP_LOG_LEVEL": "DEBUG"
}
}Running from source
# Clone the repository
git clone https://github.com/ivnvxd/mcp-server-odoo.git
cd mcp-server-odoo
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest --cov
# Run the server
python -m mcp_server_odooTesting with MCP Inspector
# Using uvx
npx @modelcontextprotocol/inspector uvx mcp-server-odoo
# Using local installation
npx @modelcontextprotocol/inspector python -m mcp_server_odooThis project is licensed under the Mozilla Public License 2.0 (MPL-2.0) - see the LICENSE file for details.
Contributions are very welcome! Please see the CONTRIBUTING guide for details.
Thank you for using this project! If you find it helpful and would like to support my work, kindly consider buying me a coffee. Your support is greatly appreciated!
And do not forget to give the project a star if you like it! ⭐