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)

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:

📖 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. 🚀