Odoo MCP Server Advanced

Two universal tools. A growing cookbook. Full Odoo API access for AI assistants.

An advanced MCP (Model Context Protocol) server for Odoo ERP — STDIO, SSE, and Streamable HTTP transports — that gives Claude, Cursor, ChatGPT-via-MCP and other AI hosts direct access to your Odoo data and workflows.

AI assistants: read AGENTS.md for the tool-first quick reference.

---

🎯 Philosophy: Simplicity & Power

Connect AI assistants to Odoo with two universal tools plus a self-improving knowledge base:

1. execute_method — call any Odoo method on any model
2. batch_execute — execute multiple operations atomically (with @N result references)
3. add_cookbook_pattern — document hard-won recipes after ≥4 failed attempts

Plus 11 discovery resources, 3 prompts, and an odoo://cookbook/patterns resource that surfaces past lessons. No specialized tools, no validation layer, no artificial limits — full Odoo API.

To rule them all. What You Can Do

Everything you need, just ask AI: automate, query, manage, customize, develop new modules, integrate with external systems, enhance your Odoo instance through AI.

---

🚀 Quick Start

Installation

Option 1: Traditional pip install

# From source
git clone https://github.com/AlanOgic/mcp-odoo-adv.git
cd mcp-odoo-adv
# Virtual Environment
python3 -m venv .venv
source .venv/bin/activate
# Installation
pip install -e .

Option 2: Using uvx (No Installation)

# From source directory
uvx --from . odoo-mcp

Option 3: Using Docker

# build STDIO
docker build -t alanogic/mcp-odoo-adv:latest -f Dockerfile .

# build SSE
docker build -t alanogic/mcp-odoo-adv-sse:latest -f Dockerfile.sse .

# build HTTP
docker build -t alanogic/mcp-odoo-adv-http:latest -f Dockerfile.http .

# Run STDIO
docker run --env-file .env alanogic/mcp-odoo-adv:latest

# Run SSE
docker run --env-file .env alanogic/mcp-odoo-adv-sse:latest

# Run HTTP
docker run --env-file .env alanogic/mcp-odoo-adv-http:latest

Configuration

Create a .env file (minimum):

cp .env.example .env
vim .env

ODOO_URL=https://your-odoo-instance.com
ODOO_DB=your-database-name
ODOO_USERNAME=your-username
ODOO_PASSWORD=your-password-or-api-key

Optional: Custom Configuration Directory

Organize multiple Odoo configurations by setting a custom directory:

# Create custom config directory
export ODOO_CONFIG_DIR=~/mcp-odoo-env
mkdir -p $ODOO_CONFIG_DIR

# Copy and configure
cp .env.example $ODOO_CONFIG_DIR/.env
vim $ODOO_CONFIG_DIR/.env

# Run server (automatically uses custom directory)
odoo-mcp

This is useful for:

• Managing multiple Odoo instances (dev, staging, production)
• Organizing configs outside project directory
• Docker/Compose deployments with volume mounts

Run Server

After pip install -e ., four console scripts are wired up:

# STDIO (Claude Desktop, Claude Code, Cursor)
odoo-mcp                      # or: python -m odoo_mcp

# SSE (browsers, port 8009)
odoo-mcp-sse

# Streamable HTTP (API integrations, port 8008)
odoo-mcp-http

# HTTP with Bearer auth (production behind a reverse proxy)
odoo-mcp-http-secure

Each runner streams logs to ./logs/mcp_server_<transport>_<timestamp>.log plus stderr.

Claude Desktop Setup

Option 1: Using local installation

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "odoo": {
      "command": "python",
      "args": ["-m", "odoo_mcp"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USERNAME": "your-username",
        "ODOO_PASSWORD": "your-password"
      }
    }
  }
}

Option 2: Using uvx (Recommended - No Installation)

First, create your credentials in ~/.config/odoo/.env:

mkdir -p ~/.config/odoo
cat > ~/.config/odoo/.env << 'EOF'
ODOO_URL=https://your-instance.odoo.com
ODOO_DB=your-database
ODOO_USERNAME=your-username
ODOO_PASSWORD=your-password
EOF

Then add to claude_desktop_config.json:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["--from", "odoo-mcp", "odoo-mcp"]
    }
  }
}

Benefits:

• No installation required - uvx downloads and runs automatically
• Credentials stored securely in .env file (not in config)
• Always uses the latest published version
• Works from anywhere on your system

Option 3: Using Docker

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ODOO_URL=https://your-instance.odoo.com",
        "-e", "ODOO_DB=your-database",
        "-e", "ODOO_USERNAME=your-username",
        "-e", "ODOO_PASSWORD=your-password",
        "alanogic/mcp-odoo-adv:latest"
      ]
    }
  }
}

Or with .env file:

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/absolute/path/to/.env", "alanogic/mcp-odoo-adv:latest"]
    }
  }
}

---

🔧 The Tools

1. execute_method - The Universal Powerhouse

Execute ANY Odoo method on ANY model. Full API access. No limitations.

execute_method(
    model="<model_name>",
    method="<method_name>",
    args_json='[...]',      # Positional arguments
    kwargs_json='{...}'     # Keyword arguments
)

Examples:

# Search customers
execute_method(
    model="res.partner",
    method="search_read",
    args_json='[[["customer_rank", ">", 0]]]',
    kwargs_json='{"fields": ["name", "email"], "limit": 20}'
)

# Create sales order
execute_method(
    model="sale.order",
    method="create",
    args_json='[{"partner_id": 8, "order_line": [[0, 0, {"product_id": 5, "product_uom_qty": 1}]]}]'
)

# Confirm order
execute_method(
    model="sale.order",
    method="action_confirm",
    args_json='[[5]]'
)

2. batch_execute - Atomic Transactions

Execute multiple operations atomically. All succeed or all rollback. Use "@N" (1-indexed) inside args_json to reference a previous operation's result.

batch_execute(
    operations=[
        {"model": "res.partner", "method": "create",
         "args_json": '[{"name": "Acme"}]'},
        {"model": "sale.order", "method": "create",
         "args_json": '[{"partner_id": "@1", "order_line": [[0, 0, {"product_id": 5, "product_uom_qty": 1}]]}]'},
        {"model": "sale.order", "method": "action_confirm",
         "args_json": '[[@2]]'}
    ],
    atomic=True
)

3. add_cookbook_pattern - Self-Improving Knowledge Base

After ≥4 failed approaches to the same problem, document the working solution so future sessions skip the trial-and-error:

add_cookbook_pattern(
    problem="Search products by attribute value",
    failed_approaches=[
        "Used = on many2many field",
        "Tried dotted notation",
        "Used wrong model",
        "Passed scalar instead of list to in",
    ],
    working_solution='execute_method(model="product.template", method="search_read", args_json=\'[[["product_template_attribute_value_ids", "in", [123]]]]\')',
    why_it_works="Many2many fields require in with a list, not =",
    key_lesson="For m2m: always 'in' with a list, never '=' with scalar"
)

The ≥4 threshold is enforced — shallow trial-and-error stays out of the cookbook.

---

📚 Documentation

Discovery resources (read before guessing)

Resource	Returns
odoo://models	All models in this instance
odoo://model/{model}/schema	Full schema — fields, types, requireds, relationships
odoo://model/{model}/access	Your CRUD permissions on this model
odoo://methods/{model}	Methods available on this model
odoo://workflows	Business workflows from installed modules
odoo://server/info	Odoo version + installed modules
odoo://cookbook/patterns	Learned Patterns from past sessions (read after first failure)

Plus odoo://record/{model}/{id}, odoo://search/{model}/{domain}, odoo://fields/{model}, odoo://model/{model} for one-off reads.

The Cookbook

📖 COOKBOOK.md — 45+ practical examples:

• Searching & filtering
• Creating records
• Updating & deleting
• Working with relationships
• Business workflows
• Batch operations
• Advanced patterns

Start here! The cookbook shows you how to accomplish anything with just 2 tools.

Prompts

User-selectable templates in Claude's menu:

• search-customers — Find customers with filters
• create-sales-order — Create sales orders step-by-step
• odoo-exploration — Discover your Odoo instance capabilities

Claude Code skills

Eight skills ship in .claude/skills/ and auto-activate on relevant requests when this repo is opened in Claude Code. They wrap the cookbook into focused, trigger-aware guides:

• odoo-mcp-searching — domains, operators, name_search
• odoo-mcp-efficient-queries — pagination, fields, read_group
• odoo-mcp-crud — create/write/unlink, archive vs delete
• odoo-mcp-relationships — m2o/o2m/m2m command tuples
• odoo-mcp-workflows — action_confirm, action_post, button_validate
• odoo-mcp-batch — atomic transactions with @N references
• odoo-mcp-real-world — HR/CRM/inventory cross-model recipes
• odoo-mcp-learned-patterns — cookbook read/write workflow

Other MCP clients (Claude Desktop, Cursor) get the same knowledge portably via COOKBOOK.md and the odoo://cookbook/patterns resource.

---

🎓 Learn with examples

Example 1: Find Employees

execute_method(
    model="hr.employee",
    method="search_read",
    args_json='[[["name", "ilike", "john"]]]',
    kwargs_json='{"fields": ["name", "job_id", "department_id"], "limit": 10}'
)

Example 2: Time Off Requests

execute_method(
    model="hr.leave",
    method="search_read",
    args_json='[[
        ["employee_id", "=", 1],
        ["date_from", ">=", "2025-01-01"],
        ["state", "=", "validate"]
    ]]',
    kwargs_json='{"fields": ["employee_id", "date_from", "date_to", "holiday_status_id"]}'
)

Example 3: Create Customer + Order (Atomic)

batch_execute(
    operations=[
        {
            "model": "res.partner",
            "method": "create",
            "args_json": '[{"name": "Acme Corp", "email": "contact@acme.com"}]'
        },
        {
            "model": "sale.order",
            "method": "create",
            "args_json": '[{"partner_id": 123, "order_line": [[0, 0, {"product_id": 5}]]}]'
        }
    ],
    atomic=True
)

---

💡 Why This Design Works

✅ Key Benefits

1. Universal Access

• Full Odoo API at your fingertips
• No artificial limitations
• Do anything Odoo can do

2. Simple & Predictable

• Learn 2 tools, use everywhere
• Clear mental model
• Easy to debug and maintain

3. Reliable

• Odoo provides excellent native error messages
• Direct API access means fewer points of failure
• Stable, production-ready implementation

4. Flexible

• Works with several Odoo version (14+)
• Supports all Odoo models and methods
• Extensible through Odoo's native capabilities

---

🔥 Features

AI Integration

• Claude Desktop / Claude Code / Cursor Ready: Works with any MCP host
• Universal Tools: execute_method + batch_execute reach the entire Odoo API
• Self-improving cookbook: odoo://cookbook/patterns resource + add_cookbook_pattern tool grow the institutional knowledge automatically
• Smart Limits: Automatic protection against oversized queries (DEFAULT=100, MAX=1000)
• MCP 2025-06-18 spec: Built on FastMCP 2.12+

Multiple Connection Options

• STDIO: Direct integration with Claude Desktop
• SSE: Server-Sent Events for web browsers (port 8009)
• HTTP: Streamable HTTP for API integrations (port 8008)
• Docker: Pre-built containers for all transports

Enterprise Ready

• Odoo 18 primary target: Works out of the box with Odoo 14-18 via JSON-RPC
• Odoo 19+ opt-in: JSON-2 Bearer token API available via ODOO_API_VERSION=json-2
• Flexible Auth: Environment variables or config files
• Enhanced Logging: Timestamped logs in ./logs/
• Proxy Support: HTTP proxy configuration
• SSL Control: Configurable SSL verification
• Python 3.10-3.13: Tested on all current Python versions

---

🚀 Advanced Usage

API keys

Odoo 18 (default): use the JSON-RPC path with an API key in the password slot.

export ODOO_API_VERSION=json-rpc   # default, can be omitted
export ODOO_PASSWORD=your_api_key_here

Generate the key in Odoo: Preferences → Account Security → New API Key.

Odoo 19+ (opt-in upgrade): JSON-2 Bearer token API.

export ODOO_API_VERSION=json-2
export ODOO_API_KEY=your_api_key_here

JSON-2 is future-proof — JSON-RPC is scheduled for removal in Odoo 20 (fall 2026).

Docker Deployment

# STDIO transport (Claude Desktop)
docker run -i --rm --env-file .env alanogic/mcp-odoo-adv:latest

# SSE transport (Web browsers)
docker run -p 8009:8009 --env-file .env alanogic/mcp-odoo-adv:sse

# HTTP transport (API integrations)
docker run -p 8008:8008 --env-file .env alanogic/mcp-odoo-adv:http

Domain Operators

Common search operators:

Operator	Description	Example
=	Equal	["country_id", "=", 75]
!=	Not equal	["active", "!=", false]
>, >=, <, <=	Comparison	["amount_total", ">=", 1000]
like, ilike	Pattern match	["name", "ilike", "acme"]
in, not in	In list	["state", "in", ["draft", "sent"]]

---

📖 Documentation

New to Odoo MCP Server? Start here:

1. USER_GUIDE.md - Complete setup guide with 5-minute quick-start
2. COOKBOOK.md - 45+ practical examples for common tasks
3. DOCKER.md - Docker deployment guide (containers, compose, production)
4. TRANSPORTS.md - Connection options (STDIO, SSE, HTTP)
5. CLAUDE.md - Technical reference and architecture
6. CHANGELOG.md - Version history and updates

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open Pull Request

Development philosophy:

• Simplicity first
• Universal tools over specialized ones
• Documentation over complexity
• Reliability through directness

---

📝 License

GNU General Public License v3.0 or later (GPL-3.0-or-later) - See LICENSE file

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

---

🙏 Acknowledgments

• Original project by Lê Anh Tuấn
• Built with FastMCP
• Follows Model Context Protocol specification

---

🎯 What's Next?

Ready to get started?

1. Quick Setup: Follow the USER_GUIDE.md 5-minute quick-start
2. Learn by Example: Browse COOKBOOK.md for 45+ recipes
3. Explore Your Odoo: Use the odoo-exploration prompt in Claude
4. Build & Automate: Create custom workflows with execute_method

Need help?

• 📖 Check the USER_GUIDE.md troubleshooting section
• 💬 Open an issue on GitHub
• 🌟 Star the repo if you find it useful!

---

Connect AI to Odoo. Build the future. 🚀