🔌 mcp-server-odoo

A Model Context Protocol 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:

🖥️ With Claude Code

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:

{
  "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. This also disables save_binary_field, because it writes files to the machine running the server:

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

✏️ Write Operations

🚫 Write tools and save_binary_field 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:

# 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:

Alternatively, create a .env file in the project root.

📋 Requirements

• 🐍 Python >= 3.10
• 📦 uv (recommended) or pip
• 🏢 Access to an Odoo instance (12.0+) with XML-RPC enabled

📜 License

AGPL-3.0-or-later