odoo-mcp 0.6.0

MCP Server for Odoo Integration

Odoo MCP

The Odoo MCP that is fluent in every Odoo version.
Five-minute install. Zero Odoo-side setup. Safe writes, real diagnostics, JSON-2 ready years before the Odoo 22 XML-RPC removal.

Odoo MCP turns any Odoo 16+ database into a Model Context Protocol server — using only your existing credentials. No App Store module, no permission setup, no admin access required. Built for local agents, IDEs, and automation tools that need real Odoo context without hand-rolled scripts or unsafe direct write access.

It speaks XML-RPC for Odoo 16-18 and External JSON-2 for Odoo 19+. It exposes a compact MCP surface with read tools, diagnostics, schema discovery, migration helpers, local addon scanning, and a gated write workflow. One server can serve multiple named Odoo instances at once.

Try it in 30 seconds

Once configured (see Install and Configure), ask your agent things like:

"Show me all customers from Spain with unpaid invoices."

"Find products with stock below 10 units in the main warehouse."

"Audit the custom_billing addon for upgrade risks before we move to Odoo 19."

Highlights

Capability	What it gives you
26 MCP tools	Read records, aggregate server-side, post chatter, inspect schema, build domains, scan addons, diagnose calls, access rules, resolve model renames, and validate writes.
Multi-instance	One server, several named Odoo instances — optional instance parameter on every tool, list_instances discovery, instance-bound approval tokens, per-instance schema caches.
5 agent prompts	Reusable workflows for failed calls, fit/gap workshops, JSON-2 migration, safe writes, and module audits.
Odoo 16-19 coverage	XML-RPC by default, JSON-2 opt-in for Odoo 19.
Streamable HTTP	Local HTTP/SSE support for clients that do not use stdio.
Smart field selection	search_records and read_record curate business-relevant fields when no fields argument is supplied — drops audit, message, binary, and unstored compute noise. Pass fields=["*"] to opt out.
Server-side aggregation	aggregate_records pushes groupby/sum/count/avg into Postgres via formatted_read_group (Odoo 19+) or read_group (16-18).
Chatter integration	chatter_post adds messages to any mail.thread record under the same approval-token gate as writes — or directly via MCP_CHATTER_DIRECT=1.
Locale plumbing	ODOO_LOCALE injects context.lang automatically on every Odoo call (caller can override).
Structured logging	JSON formatter and rotating file handler via ODOO_MCP_LOG_LEVEL, ODOO_MCP_LOG_JSON, ODOO_MCP_LOG_FILE.
Safe writes	Direct create, write, and unlink are blocked; approved writes require live metadata, a same-session token, explicit confirmation, and an env gate.
Human-in-the-loop approval	ODOO_MCP_ELICIT_WRITES=1 shows a native MCP confirmation form (with a diff summary) before any approved write executes — token flow stays as fallback.
Audit trail	ODOO_MCP_AUDIT_LOG appends one JSONL line per write-path event (preview, validate, execute, chatter) with instance and token digest.
Resilience	Read-only calls retry connection errors with exponential backoff; schema caches are TTL- and LRU-bounded; health_check flags N+1 read loops.
Real smoke tests	Docker Compose validation boots disposable Odoo 16.0, 17.0, 18.0, and 19.0 stacks, including restricted users, custom record rules, and packaged addon XML install/update.

Why Odoo MCP

Trait	Odoo MCP	Other MCP-Odoo bridges
Setup steps on Odoo side	0 — works with any Odoo 16+ instance using credentials you already have.	Often require installing an App Store module, configuring enabled models, and granting per-tool permissions.
Safe write workflow	Approval token + live fields_get validation + explicit confirm + env gate.	Often expose direct create/write/unlink or a "yolo" bypass.
Diagnostics	diagnose_odoo_call, diagnose_access, inspect_model_relationships, upgrade_risk_report, fit_gap_report, business_pack_report, scan_addons_source.	Usually CRUD only.
Transport	XML-RPC (16+) and External JSON-2 (Odoo 19+). Ready for the Odoo 22 XML-RPC removal years early.	Usually XML-RPC only — deprecated since Odoo 19, removed in Odoo 22.
Migration helpers	generate_json2_payload previews the JSON-2 body for any XML-RPC call before you migrate.	None.
Multi-instance	Named instances in one config file, per-tool routing, tokens and caches isolated per instance.	Usually one global connection per server process.
Agent prompts	5 ready-made prompts for diagnose / fit-gap / JSON-2 migration / safe-write / module-audit.	Usually none.
HTTP transport security	DNS-rebinding protection, host/origin allowlists, local-bind by default.	Often missing.
Real Odoo smoke tests	Docker Compose harness boots disposable Odoo 16/17/18/19 stacks per release.	Often mock-based only.
Framework examples	Copy-paste adapters for Cursor, Claude Code, OpenAI Agents, LangGraph, CrewAI, and n8n in examples/.	None.
Audit & approval UX	JSONL audit trail + native elicitation confirm forms — without installing anything in Odoo.	Audit features usually require an Odoo-side module.

Install

The fastest path is uvx, which fetches the package on demand:

uvx odoo-mcp --health

Or install into your environment:

pip install odoo-mcp
# or: pipx install odoo-mcp

Pull the prebuilt container from GitHub Container Registry:

docker pull ghcr.io/tuanle96/mcp-odoo:latest

For local development:

git clone https://github.com/tuanle96/mcp-odoo.git
cd mcp-odoo
uv sync --extra dev

Configure

Set connection values in the environment:

export ODOO_URL="https://your-odoo-instance.com"
export ODOO_DB="your-database"
export ODOO_USERNAME="your-user"
export ODOO_PASSWORD="your-password-or-api-key"
export ODOO_TRANSPORT="xmlrpc"

For Odoo 19 JSON-2:

export ODOO_TRANSPORT="json2"
export ODOO_API_KEY="your-odoo-api-key"
export ODOO_JSON2_DATABASE_HEADER="1"

ODOO_JSON2_DATABASE_HEADER=1 sends X-Odoo-Database on JSON-2 calls. Set it to 0 only when host or dbfilter routing already selects the intended database.

Optional environment variables:

Variable	Default	Effect
ODOO_CONFIG_FILE	unset	Explicit path to a config file, checked before the standard locations.
ODOO_LOCALE	unset	Inject context.lang on every Odoo call. Caller-supplied context.lang always wins.
ODOO_MCP_MAX_SMART_FIELDS	15	Cap for smart-field selection when caller omits fields.
ODOO_MCP_LOG_LEVEL	INFO	Process logger level (DEBUG/INFO/WARNING/ERROR/CRITICAL).
ODOO_MCP_LOG_JSON	0	Truthy → emit JSON-formatted log lines.
ODOO_MCP_LOG_FILE	unset	Path → enable rotating file handler (10MB × 3 backups).
ODOO_MCP_ENABLE_WRITES	0	Required for execute_approved_write.
ODOO_MCP_ALLOWED_SIDE_EFFECT_METHODS	empty	Exact model.method allowlist (e.g. sale.order.action_confirm).
ODOO_MCP_POLICY_FILE	./odoo_mcp_policy.json if present	Version-controllable side-effect allowlist with review metadata (see odoo_mcp_policy.json.example); merged with the env allowlist.
ODOO_MCP_ALLOW_UNKNOWN_METHODS	0	Broad mode for execute_method. Prefer the exact allowlist above.
ODOO_MCP_AUDIT_LOG	unset	Path → append one JSONL line per write-path event (preview/validate/execute/chatter), tokens stored as digests.
ODOO_MCP_ELICIT_WRITES	0	Truthy → execute_approved_write asks the human via MCP elicitation (native confirm form with a diff summary) before executing; falls back to the token flow when the client cannot elicit.
ODOO_MCP_RETRY_ATTEMPTS	2	Extra attempts for read-only calls on connection errors (0–5). Writes never retry.
ODOO_MCP_RETRY_BACKOFF	0.5	Base retry backoff seconds; doubles per retry.
ODOO_MCP_SCHEMA_CACHE_TTL	600	Schema cache entry lifetime in seconds.
ODOO_MCP_SCHEMA_CACHE_MAX	256	Max schema cache entries (LRU eviction).
MCP_CHATTER_DIRECT	0	Truthy → chatter_post skips the approval token gate and posts immediately.
MCP_ALLOW_REMOTE_HTTP	0	Truthy → permit non-local HTTP binds (still requires external auth/TLS).
MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS	local	CSV allowlists for HTTP transports.

You can also use odoo_config.json:

{
  "url": "https://your-odoo-instance.com",
  "db": "your-database",
  "username": "your-user",
  "password": "your-password-or-api-key"
}

Multiple Odoo instances

One server can talk to several Odoo databases. Add an instances map to your config file (auto-detected — a file without instances keeps the flat single-instance shape above):

{
  "default": "acme",
  "instances": {
    "acme": {
      "url": "https://acme.odoo.com",
      "db": "acme",
      "username": "bot",
      "api_key": "...",
      "transport": "json2"
    },
    "globex": {
      "url": "https://globex.odoo.com",
      "db": "globex",
      "username": "bot",
      "password": "...",
      "lang": "fr_FR",
      "timeout": 60
    }
  }
}

• Every read/write tool accepts an optional instance parameter; omitted → the default instance. default itself is optional when only one instance is defined.
• Each entry supports the same keys as the flat config (url, db, username, password, api_key, transport, json2_database_header, lang) plus timeout and verify_ssl. Instance entries are self-contained: credentials and transport never fall back to env vars (so one instance can never inherit another deployment's ODOO_API_KEY). Only non-credential knobs (ODOO_TIMEOUT, ODOO_VERIFY_SSL, ODOO_LOCALE) act as fallback defaults for entries that omit them. Env overrides like ODOO_TRANSPORT/ODOO_API_KEY still apply to legacy flat configs, as before.
• ODOO_CONFIG_FILE=/path/to/config.json points at an explicit config file, checked before ./odoo_config.json, ~/.config/odoo/config.json, and ~/.odoo_config.json.
• Precedence: when ODOO_URL/ODOO_DB/ODOO_USERNAME/ODOO_PASSWORD are all set, the environment wins and defines a single instance named default — unset them to use a multi-instance file.
• Instance names must match [A-Za-z0-9_-]{1,64}. Clients connect lazily — an instance is only contacted when a tool targets it.
• Discovery: the list_instances tool returns configured names, URLs, databases, and transports — never credentials.
• Write-approval tokens encode the instance name, so a token validated against one instance can never execute on another.
• MCP resources (odoo://…) always use the default instance in this release; use tools for multi-instance access.

Run

Start the MCP server over stdio:

odoo-mcp

or:

python -m odoo_mcp

Start Streamable HTTP for local clients:

odoo-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

Non-local HTTP binds are rejected unless you pass --allow-remote-http or set MCP_ALLOW_REMOTE_HTTP=1. This server does not include built-in HTTP authentication. Put remote HTTP deployments behind your own authentication, TLS, and network policy.

Check runtime posture without starting the server loop:

odoo-mcp --health

MCP Tools

26 tools grouped by use case. Each tool name is a single-purpose handle the agent can call. Tools that talk to Odoo accept an optional instance parameter when multiple instances are configured (see Multiple Odoo instances).

Read & Discover (10)

Tool	Purpose
list_models	List Odoo model technical names and labels.
get_model_fields	Read field metadata for one model.
search_records	Run bounded read-only search_read. Smart-field selection when caller omits fields.
read_record	Read one record by model and ID. Smart-field selection when caller omits fields.
aggregate_records	Server-side groupby/aggregation via formatted_read_group (Odoo 19+) or read_group (16-18).
search_employee	Search employees by name.
search_holidays	Search leave records by date range.
get_odoo_profile	Read server version, user context, transport, database, and installed module summary.
schema_catalog	Build a bounded model catalog with optional field metadata.
build_domain	Build and validate an Odoo domain from structured conditions.

Write & Operate (5)

Tool	Purpose
preview_write	Produce a non-executing approval payload for create, write, or unlink.
validate_write	Validate a write payload against trusted live fields_get metadata.
execute_approved_write	Execute only a same-session, live-validated, confirmed write when ODOO_MCP_ENABLE_WRITES=1.
execute_method	Execute a reviewed model method. Direct create, write, and unlink are blocked. Side-effect methods require an exact allowlist or ODOO_MCP_ALLOW_UNKNOWN_METHODS=1.
chatter_post	Post a chatter message on a mail.thread record. Default mode requires the approval-token preview/execute flow.

Diagnose (3)

Tool	Purpose
diagnose_odoo_call	Diagnose a model call without executing it.
diagnose_access	Diagnose ACL and record-rule visibility for the current Odoo credential.
inspect_model_relationships	Group relationship fields, required fields, and create/write hints.

Migrate (3)

Tool	Purpose
generate_json2_payload	Convert XML-RPC-shaped input into JSON-2 endpoint, headers, and named body.
upgrade_risk_report	Surface transport, method, and migration risks across Odoo versions.
lookup_model_history	Resolve outdated model names (account.invoice → account.move) against a curated per-version rename catalog.

Audit & Plan (3)

Tool	Purpose
scan_addons_source	Scan local addon source without importing addon code.
fit_gap_report	Classify requirements into standard, configuration, Studio, custom module, avoid, or unknown.
business_pack_report	Report expected modules, models, and discovery calls for sales, CRM, inventory, accounting, or HR.

Utility (2)

Tool	Purpose
health_check	Report non-secret MCP runtime posture.
list_instances	List configured Odoo instance names, URLs, databases, and transports — never credentials.

Resources

URI	Description
odoo://models	List available models.
odoo://model/{model_name}	Read model metadata and fields.
odoo://record/{model_name}/{record_id}	Read one record.
odoo://search/{model_name}/{domain}	Search records with a bounded domain.

Prompts

Prompt	Use it for
diagnose_failed_odoo_call	Root-cause a failing Odoo call before retrying.
fit_gap_workshop	Turn raw requirements into Odoo fit/gap buckets.
json2_migration_plan	Plan XML-RPC or JSON-RPC migration to External JSON-2.
safe_write_review	Review a proposed create, write, or unlink.
custom_module_audit	Audit local addon source with scan, risk, and business evidence.

Safe Write Model

Writes are intentionally boring.

1. preview_write creates a canonical, non-executing payload.
2. validate_write checks model metadata, required fields, readonly fields, relation hints, record IDs, and payload shape.
3. execute_approved_write runs only when all gates pass:
   • the approval came from validate_write in the same server process,
   • validation used trusted, non-empty live Odoo fields_get metadata,
   • the token has not expired or been consumed,
   • confirm=true is passed,
   • ODOO_MCP_ENABLE_WRITES=1 is set.

Odoo access rules, record rules, and server-side constraints still decide the final result.

Reviewed side-effect methods such as sale.order.action_confirm can be enabled one by one:

export ODOO_MCP_ALLOWED_SIDE_EFFECT_METHODS="sale.order.action_confirm,res.partner.message_post"

ODOO_MCP_ALLOW_UNKNOWN_METHODS=1 is still supported for trusted deployments, but health_check reports it as broad mode. Prefer exact allowlist entries when you only need a small number of reviewed methods.

Client Setup

Claude Desktop on macOS reads MCP configuration from:

~/Library/Application Support/Claude/claude_desktop_config.json

Use an absolute Python path because GUI apps may not inherit your shell PATH:

{
  "mcpServers": {
    "odoo": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["-m", "odoo_mcp"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_DB": "your-database",
        "ODOO_USERNAME": "your-user",
        "ODOO_PASSWORD": "your-password-or-api-key",
        "ODOO_TRANSPORT": "xmlrpc"
      }
    }
  }
}

More examples are in docs/client-configs.md.

Framework examples

Copy-paste-runnable integrations live in examples/:

Client	Example
Cursor	examples/cursor/ — .cursor/mcp.json + agent rules
Claude Code / Codex CLI	snippets in examples/README.md
OpenAI Agents SDK	examples/openai-agents/ — local + hosted variants
LangGraph	examples/langgraph/ — langchain-mcp-adapters
CrewAI	examples/crewai/ — native mcps=[...] agent
n8n	examples/n8n/ — importable workflow JSON

Docker

Use the prebuilt GHCR image:

docker pull ghcr.io/tuanle96/mcp-odoo:latest

Or build it locally:

docker build -t mcp/odoo:latest -f Dockerfile .

Run over stdio from an MCP client (replace mcp/odoo:latest with ghcr.io/tuanle96/mcp-odoo:latest to use the prebuilt image):

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "ODOO_URL",
        "-e", "ODOO_DB",
        "-e", "ODOO_USERNAME",
        "-e", "ODOO_PASSWORD",
        "-e", "ODOO_TRANSPORT",
        "-e", "ODOO_API_KEY",
        "mcp/odoo:latest"
      ]
    }
  }
}

Run Streamable HTTP locally:

docker run --rm \
  -p 127.0.0.1:8000:8000 \
  -e ODOO_URL \
  -e ODOO_DB \
  -e ODOO_USERNAME \
  -e ODOO_PASSWORD \
  -e ODOO_TRANSPORT \
  -e ODOO_API_KEY \
  mcp/odoo:latest \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --allow-remote-http

Test

Run the normal quality gates:

uv run python -m ruff check .
uv run python -m mypy src
uv run python -m pytest

Run real Odoo smoke tests:

uv run --python 3.12 --with-editable . scripts/odoo_compose_smoke.py \
  --versions 16.0 17.0 18.0 19.0 \
  --timeout 360 \
  --inspector-smoke

The smoke harness boots disposable Docker Compose stacks, validates direct Odoo access, validates MCP stdio, and for Odoo 19 also validates JSON-2 and Streamable HTTP.

Run the multi-instance smoke (one stack, three databases, two accounts on one instance):

uv run --python 3.12 --with-editable . scripts/odoo_multi_instance_smoke.py

Compatibility

XML-RPC remains the default transport for broad compatibility. Odoo 19 supports External JSON-2 through ODOO_TRANSPORT=json2. XML-RPC and JSON-RPC are deprecated since Odoo 19 and scheduled for removal in Odoo 22 (fall 2028), so new integrations should plan for JSON-2.

Documentation

Guide	Covers
docs/architecture.md	System shape, transports, safety boundaries
docs/multi-instance.md	Multi-database config, routing, isolation model
docs/troubleshooting.md	From error text to root cause (ACL, record rules, routing)
docs/performance.md	Cache/retry knobs, batching patterns, N+1 detection
docs/client-configs.md	Claude Desktop, Docker, Streamable HTTP setups
docs/testing.md	Local gates and the Docker Compose smoke harness

Contributing

Issues, pull requests, and compatibility reports are welcome. Start with CONTRIBUTING.md, include your Odoo version, transport, client type, and the verification you ran.

Security

Do not publish logs that contain Odoo credentials, API keys, database names from private environments, or full Odoo debug traces. Report vulnerabilities through SECURITY.md.

License

MIT. See LICENSE.