Ask Claude to read and write your Odoo 19 data in plain language — and stop it from doing
the dangerous parts by accident.
This server connects any Model Context Protocol (MCP) client to Odoo 19+ over the v2 JSON-2
API. An assistant discovers your models by reading schemas rather than guessing field names,
then calls any ORM method through one tool. Before anything destructive runs, a safety layer
classifies the operation and holds it behind a single-use confirmation token.
MCP Server for Odoo 19+ with v2 JSON-2 API Support
Estrellas
11
Herramientas
—
Disponibilidad
—
# The assistant reads the schema first, then queries — no guessed field names
read_resource("odoo://model/sale.order/quick-schema")
execute_method("sale.order", "search_read",
kwargs_json='{"domain": [["state", "=", "sale"]], "fields": ["name", "amount_total"], "limit": 10}')
Who this is for
You run Odoo 19+ and want an assistant that queries and updates it directly, instead of
copying data between a chat window and the ERP.
You need writes to be safe. Posting a journal entry or validating a picking is
irreversible. Every such call is gated, and eight security-critical models refuse writes
outright.
You care about token cost. Compact schemas, batched model bundles, and one-call session
bootstrap keep discovery cheap on long conversations.
If you only need read-only reporting, this still works — set a readonly role and the safety
layer blocks every non-safe method.
What you get
3 tools
execute_method reaches any method on any model; batch_execute and read_resource cover the rest
38 resources
Model discovery, compact schemas, state-machine workflows, introspection, API reference (odoo://api/*), and runtime posture (odoo://server-status)
One flag (MCP_SAFETY_MODE=locked) turns writes off, enforces a write allowlist, binds HTTP to localhost, and pre-flights payloads against live fields_get — each layer independently overridable
Multi-user mode
Per-user bearer keys and personal Odoo clients, so every write is attributed to a real person
Reference data
30 documented ORM methods, 13 modules with special-method knowledge, including the Enterprise AI module
Built on FastMCP 4 (>=4.0.10,<5): one deployment speaks both MCP 2026-07-28
(sessionless — any replica behind a plain load balancer can answer) and MCP 2025-11-25
(session-based), negotiated per connection, so older clients keep working. Background tasks,
progress tracking, icons and structured outputs are available in both. See the
migration notes.
Hardened by default: regex-validated model and method names, a non-root Docker container,
mandatory authentication on HTTP, thread-safe caches, and no traceback ever forwarded to a
client.
Server name: register this server as odoo19-mcp (the name the --setup
wizard generates and the one used in every example below). Skills installed
alongside it (distributed separately) may refer to its tools under this name, so a
different name can leave them unable to call the server's tools.
Using Docker (recommended)
Method 1: Using run-docker.sh wrapper (simplest)
Create a .env file in the project root with your credentials, then:
Restart Claude Desktop after saving the config file.
Verify the connection
Ask Claude: "List the first 5 partners in Odoo". It should call execute_method on
res.partner and come back with names.
Quick start examples
# Search partners
execute_method("res.partner", "search_read",
kwargs_json='{"domain": [["is_company", "=", true]], "fields": ["name", "email"], "limit": 10}')
# Create a partner
execute_method("res.partner", "create",
args_json='[{"name": "ACME Corp", "is_company": true, "email": "[email protected]"}]')
# Update with auto-resolved Many2one (no need to know user ID)
execute_method("res.partner", "write",
args_json='[[42], {"name": "ACME Corp Updated"}]',
resolve_json='{"user_id": {"model": "res.users", "search": "John"}}')
# Confirm a sale order (2-step safety confirmation with token)
# Step 1: triggers safety gate, returns confirmation_token in hint
result = execute_method("sale.order", "action_confirm", args_json='[[15]]')
# Step 2: confirm with the token from step 1
execute_method("sale.order", "action_confirm", args_json='[[15]]',
confirmed=true, confirmation_token='<token from step 1>')
# Several operations in one call: each is classified, and the batch confirms once,
# with one token bound to the whole operations list
batch_execute(operations=[
{"model": "sale.order", "method": "action_confirm", "args_json": "[[15]]"},
{"model": "sale.order", "method": "action_confirm", "args_json": "[[16]]"},
])
Note that confirmed=true on its own does nothing. The token is single-use, expires after
120 seconds, and is bound to the exact payload the gate inspected — so an agent cannot take a
token issued for unlink([1]) and reuse it on unlink([1, 2, …, 1000]).
Architecture
Tools (3)
Tool
Purpose
execute_method
Call any method on any Odoo model
batch_execute
Multiple operations with progress tracking
read_resource
Read any odoo:// resource by URI
Resources (38)
Resource
Description
odoo://models
List all models
odoo://model/{name}
Model info with fields
odoo://model/{name}/schema
Full fields and relationships
odoo://model/{name}/fields
Lightweight field list with labels
odoo://model/{name}/quick-schema
Ultra-compact schema (~1.5KB, short keys)
odoo://model/{name}/workflow
State machine transitions and side effects
odoo://model/{name}/docs
Rich docs: labels, help text, selections
odoo://bundle/{models}
Batch quick-schema for N models (max 10)
odoo://session-bootstrap
Bootstrap: schemas + workflows for common models
odoo://record/{model}/{id}
Get a specific record by ID
odoo://methods/{model}
Available methods (enriched with live signatures)
odoo://docs/{model}
Documentation URLs
odoo://concepts
Business term to model mappings
odoo://find-model/{concept}
Natural language to model name
odoo://tools/{query}
Search available operations
odoo://actions/{model}
Discover model actions
odoo://templates
List all resource templates
odoo://tool-registry
Pre-built workflows
odoo://module-knowledge
Special methods knowledge
odoo://module-knowledge/{name}
Knowledge for a specific module
odoo://workflows
Business workflows
odoo://server/info
Odoo server information
odoo://domain-syntax
Domain operator reference
odoo://pagination
Pagination guide
odoo://hierarchical
Parent/child tree query patterns
odoo://aggregation
Aggregation guide (formatted_read_group)
odoo://model-limitations
Known model issues + runtime problems
odoo://server-status
Runtime safety posture (mode, host, allowlist, warnings). Non-secret. New in v1.16.0.
odoo://api/json2-protocol
JSON-2 contract: body keys, error shape, status codes, transaction rule. New in v1.18.0.
odoo://api/version-drift
ORM renames since 15.2 (name_get, args→domain, read_group…) and what to call instead. New in v1.18.0.
odoo://api/x2many-commands
One2many/Many2many command triples with examples. New in v1.18.0.
odoo://api-index
Live catalogue of installed modules and readable models (/doc-bearer/index.json, cached per user). New in v1.18.0.
odoo://api/datetime
Server date formats, UTC storage, client-side tz, dynamic domain values ('-3d +1H'), date parts. New in v1.18.0.
odoo://api/mail-thread
message_post signature, notification kill-switch context keys, followers, activities. New in v1.18.0.
odoo://api/security-model
How ACLs, record rules and field groups compose; has_access / has_group checks. New in v1.18.0.
odoo://api/web-read
web_read / web_search_read / web_save nested specification. New in v1.18.0.
odoo://api/xmlids
XML id resolution over JSON-2 (check_object_reference) and custom model/field constraints. New in v1.18.0.
odoo://session
Live identity: uid, login, lang, tz, current and allowed companies, installed languages. New in v1.18.0.
Confirm in strict / locked for any record count; proceed in permissive
Conditional
HIGH
Always require confirmation
Always
BLOCKED
Always refuse
N/A
Blocked models (write always refused)
ir.rule, ir.model.access, ir.access, ir.module.module, ir.config_parameter, res.users, res.groups, res.users.apikeys, plus the models that act on one of those without naming it: password wizards (change.password.*), res.config.settings, res.groups.privilege, ir.model.data, base_import.import, the base.module.* wizards, mail servers, auth providers, portal wizards, and the credential / 2FA / session satellites of res.users.
Only writes are blocked — reads stay open on every model, the connected Odoo account's rights decide what is readable. A blocked model is also protected against indirect writes: x2many commands, default_<field> context keys and load column paths that would create, change or delete its records through an allowed model (res.partner.user_ids → res.users) are refused. Every value shape Odoo turns into such a write is judged the same way: null/false on an x2many is Odoo's clear (which deletes the lines of a one2many whose inverse cascades), and a bare dict in an x2many list is a new record.
These run code or reshape the database. STDIO, the static MCP_API_KEY and the admin role may write to them — automations, scheduled actions, custom models and fields — and every side-effect call confirms, in every safety mode. Any other multi-user role is refused.
If confirmation needed: returns pending_confirmation=true with safety classification and a confirmation_token in the hint field
Caller reviews, then re-calls with confirmed=true AND confirmation_token='<token>'
Tokens are single-use, expire after 120s, and are bound to the specific model+method. This prevents agents from bypassing the safety gate by always passing confirmed=true.
Locked mode (v1.16.0)
MCP_SAFETY_MODE=locked adds four overlapping protections on top of the classifier and token gate. Designed for safe-by-default deployments where a colleague might point an over-eager AI agent at their own Odoo instance.
Protection
Default under locked
Override env var
Global write kill-switch
on
MCP_READ_ONLY=false
Side-effect allowlist enforced
on (empty list = no writes)
populate MCP_WRITE_ALLOWLIST
HTTP bind
127.0.0.1 (localhost-only)
MCP_HOST=0.0.0.0
Live fields_get payload pre-flight
on
MCP_VALIDATE_PAYLOADS=false
Each protection is independently overridable — set locked and tune the individual flags as needed. permissive and strict semantics are unchanged from v1.14.0; no existing deploy changes posture on upgrade unless the operator opts in.
Allowlist syntax: MCP_WRITE_ALLOWLIST="sale.order.action_confirm,res.partner.message_post,product.product.*". Each entry is model.method or model.* (any method on the model). Cross-model wildcards (*.method) are rejected — too easy to over-grant.
Three typical configurations:
# Safe-by-default — paste this and forget
MCP_SAFETY_MODE=locked
# Locked but allow specific side-effect methods
MCP_SAFETY_MODE=locked
MCP_READ_ONLY=false
MCP_WRITE_ALLOWLIST=res.partner.message_post,sale.order.action_confirm
# Power user — current v1.14.0 behaviour, no changes
MCP_SAFETY_MODE=strict
Posture introspection: read odoo://server-status to see the resolved profile at runtime — current mode, host, allowlist contents, and any foot-gun warnings (e.g. locked + MCP_HOST=0.0.0.0, or locked + MCP_READ_ONLY=false). The startup banner shows a one-line summary: [SAFETY locked · READ-ONLY · BIND 127.0.0.1 · ALLOWLIST 0 entries].
Payload pre-flight (MCP_VALIDATE_PAYLOADS=true): before issuing a confirmation token for a write, the validator fetches fields_get for the target model (60s LRU cache) and rejects payloads that reference non-existent fields, write to readonly fields, or arrive when the connection is silently down (fields_get returns {}). Catches hallucinated field names before they reach Odoo.
DX Improvements (v1.11.0)
Token-efficient discovery
Quick schema
odoo://model/{model}/quick-schema — Ultra-compact schema with short keys: t (type), req (required), ro (readonly), rel (relation). ~60-80% smaller than /fields.
Bundle
odoo://bundle/res.partner,sale.order,stock.picking — Batch quick-schema for up to 10 models in one call.
Session bootstrap
odoo://session-bootstrap — One call to bootstrap a conversation with schemas + workflows for common models. Configure via MCP_BOOTSTRAP_MODELS env var.
Workflow
odoo://model/{model}/workflow — State machine transitions for 6 main models with side effects and irreversibility flags. Dynamic fallback for unmapped models.
Many2one resolution
Auto-resolve field names to IDs with resolve_json:
The HTTP transport above serves a single Odoo account behind one static MCP_API_KEY.
For teams, set USERS_DB_PATH to switch into multi-user mode: many users share one
server process, each authenticating with their own bearer token and acting as their own
Odoo account — so every write is attributed to the real person, not a shared service user.
How it works
Registry — users, their per-server API keys and encrypted Odoo credentials live in
a SQLite registry (users.db) owned and written by CLORAG (a
companion app with an /admin/users page). This server is a pure reader — it opens
the database with mode=ro and never writes.
Per-request identity — an incoming bearer token is hashed (sha256) and looked up in
the registry. The caller gets a personal OdooClient built from their stored Odoo
username + decrypted API key (cached 300s, re-checked on credential rotation). Plaintext
keys are never stored; the static MCP_API_KEY still works and maps to an env-admin
identity — the only one served by the env Odoo account.
Fail-closed identity — a call that reaches the server without the caller's key is
refused, never served by the env account with the operator's role. Only a server started
on STDIO by python -m odoo_mcp (or odoo-mcp-19), where nobody authenticates, treats a
key-less call as the operator; that and the registry in use are fixed at startup, so no
later environment change (.env reload, MCP_TRANSPORT, FASTMCP_TRANSPORT) reopens it.
Roles — admin → unrestricted; readonly → read-only, with the safety layer blocking
every non-safe method; other roles → normal safety rules on their own account.
The overlay mounts the CLORAG data dir read-only at /registry and injects the encryption
key as a Docker secret. The TOKEN_ENCRYPTION_KEY and the .token_salt file must be
identical to CLORAG's, or stored credentials cannot be decrypted. In multi-user mode the
env ODOO_* credentials become optional (only the env-admin fallback uses them), though
ODOO_URL / ODOO_DB are still needed to build per-user clients.
Configuration
Variable
Required
Default
Description
ODOO_URL
Yes
—
Odoo server URL
ODOO_DB
Yes
—
Database name
ODOO_USERNAME
Yes
—
Username
ODOO_API_KEY
Yes
—
API key (Preferences → Account Security)
ODOO_PASSWORD
No
—
Password (fallback if no API key)
ODOO_TIMEOUT
No
30
Request timeout in seconds
ODOO_VERIFY_SSL
No
true
SSL certificate verification
ODOO_CONFIG_DIR
No
—
Extra directory searched first for a .env, ahead of ./.env then ~/.config/odoo/.env
MCP_TRANSPORT
No
stdio
Transport: stdio or streamable-http
MCP_API_KEY
HTTP: this orUSERS_DB_PATH
—
Static bearer token (single-user HTTP, or admin fallback in multi-user mode). HTTP server sys.exit(1) if neither is set
USERS_DB_PATH
No
—
Path to the CLORAG registry (users.db) → enables multi-user mode
TOKEN_ENCRYPTION_KEY / TOKEN_ENCRYPTION_KEY_FILE
With USERS_DB_PATH
—
Secret to decrypt registry Odoo credentials — must equal CLORAG's value
MCP_HOST
No
0.0.0.0 (127.0.0.1 under locked)
HTTP bind address. Default flips to localhost when MCP_SAFETY_MODE=locked.
MCP_PORT
No
8080
HTTP port
MCP_VERBOSE
No
true
Slant-ASCII startup banner to stderr (version, transport, masked creds, safety mode, capability counts). false to silence
MCP_SAFETY_MODE
No
strict
permissive, strict, or locked (v1.16.0). locked activates MCP_READ_ONLY=true, MCP_WRITE_ALLOWLIST enforcement, MCP_HOST=127.0.0.1 default, and MCP_VALIDATE_PAYLOADS=true.
MCP_READ_ONLY
No
derived from mode
true to reject every method that is not a known read. Fail-closed: the gate is method not in SAFE_METHODS, so unrecognised methods (message_post, toggle_active, convert_opportunity, create_from_urls, …) are blocked rather than assumed safe. The 13 SAFE_METHODS (search_read, read, fields_get, …) pass through.
MCP_WRITE_ALLOWLIST
No
empty
Comma-separated model.method (or model.*) entries permitted as side effects. Enforced under locked mode, or whenever set explicitly.
MCP_VALIDATE_PAYLOADS
No
derived from mode
true to validate write payloads against live fields_get before issuing a confirmation token. Catches hallucinated fields and readonly writes.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Odoo MCP 19?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Odoo MCP 19 necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Odoo MCP 19?
Odoo MCP 19 se ejecuta localmente por stdio.
¿Cuándo se comprobó Odoo MCP 19 por última vez?
Última comprobación: 2026-10-28. MCP Server for Odoo 19+ with v2 JSON-2 API Support