Content
# 🔌 mcp-server-odoo
A [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI
assistants full access to your Odoo ERP instance over XML-RPC.
No Odoo module installation required. Just point it at any Odoo 12+ instance.
```
🤖 AI Assistant (Claude Code, Claude Desktop, etc.)
│ MCP (stdio)
▼
📡 mcp-server-odoo
│ XML-RPC
▼
🏢 Odoo Instance
```
## ⚡ Quick Start
No cloning required — just run directly from GitHub with [uv](https://docs.astral.sh/uv/):
### 🖥️ With Claude Code
```bash
claude mcp add odoo \
-e ODOO_URL=http://localhost:8069 \
-e ODOO_DB=mydb \
-e ODOO_USER=admin \
-e ODOO_PASSWORD=admin \
-- uvx --from git+https://github.com/altinkaya-opensource/odoo-mcp mcp-server-odoo
```
### 🖱️ With Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"odoo": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/altinkaya-opensource/odoo-mcp",
"mcp-server-odoo"
],
"env": {
"ODOO_URL": "http://localhost:8069",
"ODOO_DB": "mydb",
"ODOO_USER": "admin",
"ODOO_PASSWORD": "admin"
}
}
}
}
```
### 🔒 Readonly Mode
Block all write operations by adding `READONLY_MODE=true`:
```bash
claude mcp add odoo \
-e ODOO_URL=http://localhost:8069 \
-e ODOO_DB=mydb \
-e ODOO_USER=admin \
-e ODOO_PASSWORD=admin \
-e READONLY_MODE=true \
-- uvx --from git+https://github.com/altinkaya-opensource/odoo-mcp mcp-server-odoo
```
## 🛠️ Tools
### 📖 Read Operations
| Tool | Description |
| ------------------- | --------------------------------------------------------------------------------- |
| `search_records` | 🔍 Search any model with domain filters, field selection, pagination, and sorting |
| `read_record` | 📄 Read a single record by ID with smart field selection |
| `get_record_count` | 🔢 Count records matching a domain filter (lightweight, no data fetched) |
| `list_models` | 📋 List all non-transient models available in the database |
| `get_model_fields` | 🏗️ Inspect field definitions (type, required, help text, etc.) for any model |
| `read_group` | 📊 Group records and compute aggregations (sum, avg, count) with date granularity |
| `save_binary_field` | 💾 Save a binary/image field from a record directly to a local file |
### ✏️ Write Operations
| Tool | Description |
| ---------------- | ------------------------------------------------------------------------------------- |
| `create_record` | ➕ Create a new record in any model |
| `update_record` | 📝 Update fields on an existing record |
| `delete_record` | 🗑️ Delete a record by ID |
| `copy_record` | 📋 Duplicate an existing record with optional field overrides |
| `execute_method` | ⚙️ Call any business method (e.g. `action_confirm`, `button_validate`, `action_post`) |
> 🚫 Write tools are disabled when `READONLY_MODE=true`.
## ✨ Features
### 🧠 Smart Field Selection
When you don't specify which fields to fetch, the server automatically picks the most
useful ones. It scores fields based on type, importance patterns (`state`, `amount`,
`partner`, etc.), and excludes noisy fields like `message_ids`, binary blobs, and
computed non-stored fields. You always get `id`, `name`, `display_name`, and `active`.
Pass `fields=["__all__"]` to override and get everything.
### 🔄 Flexible Domain Parsing
Domains can be passed as JSON strings, Python repr strings, or native lists:
```python
# All of these work:
[["is_company", "=", true]]
'[["is_company", "=", true]]'
"[('is_company', '=', True)]"
```
### 📅 ISO 8601 Dates
Odoo's `"2025-06-07 21:55:52"` datetime strings are automatically converted to
`"2025-06-07T21:55:52+00:00"` for standard ISO 8601 output.
## 💡 Tool Usage Examples
**🔍 Search for Turkish companies:**
```
search_records("res.partner", [["is_company", "=", true], ["country_id.code", "=", "TR"]], limit=20)
```
**🔢 Count open sale orders:**
```
get_record_count("sale.order", [["state", "=", "sale"]])
```
**📄 Read a specific product with all fields:**
```
read_record("product.product", 42, fields=["__all__"])
```
**✅ Confirm a sale order:**
```
execute_method("sale.order", "action_confirm", [42])
```
**📦 Validate a stock picking:**
```
execute_method("stock.picking", "button_validate", [15])
```
**💰 Post an invoice:**
```
execute_method("account.move", "action_post", [100])
```
**📋 Duplicate a sale order with a different partner:**
```
copy_record("sale.order", 10, default={"partner_id": 99})
```
**💾 Save a product image to disk:**
```
save_binary_field("product.product", 42, "image_1920", "/tmp/product_image.png")
```
**📊 Total sales by partner:**
```
read_group("sale.order", "partner_id", domain=[["state", "=", "sale"]], fields=["amount_total:sum"])
```
**📅 Monthly order counts:**
```
read_group("sale.order", "date_order:month", fields=["id:count"])
```
**📈 Average price by category:**
```
read_group("product.template", "categ_id", fields=["list_price:avg"])
```
**🏗️ Discover fields on a model:**
```
get_model_fields("sale.order", attributes=["string", "type", "required"])
```
## ⚙️ Configuration
All configuration is done through environment variables:
| Variable | Required | Default | Description |
| ------------------------ | -------- | ------- | ----------------------------------------------- |
| `ODOO_URL` | ✅ | | Odoo server URL (e.g. `http://localhost:8069`) |
| `ODOO_DB` | ✅ | | Database name |
| `ODOO_USER` | ✅ | | Username |
| `ODOO_PASSWORD` | ✅ | | Password or API key |
| `READONLY_MODE` | | `false` | Set to `true` to disable all write operations |
| `ODOO_MCP_LOG_LEVEL` | | `INFO` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `ODOO_MCP_LOG_FILE` | | stderr | Path to log file |
| `ODOO_MCP_DEFAULT_LIMIT` | | `10` | Default record limit for search operations |
Alternatively, create a `.env` file in the project root.
## 📋 Requirements
- 🐍 Python >= 3.10
- 📦 [uv](https://docs.astral.sh/uv/) (recommended) or pip
- 🏢 Access to an Odoo instance (12.0+) with XML-RPC enabled
## 📜 License
AGPL-3.0-or-later
