Odoo Assistant MCP Server

An Odoo virtual employee via the Model Context Protocol (MCP). This server exposes Odoo's business logic, records, and workflows to LLMs, allowing them to query, create, update, and act on Odoo data safely.

Quickstart

1. Install

Run the server directly:

uvx odoo-assistant

Or install it into your environment:

uv pip install odoo-assistant

Installing from source for development remains possible:

uv pip install git+https://github.com/singleflo/odoo-assistant-mcp

2. Configure Environment Variables

• ODOO_BASE_URL: Mandatory always. The base URL of your Odoo instance, with no trailing slash (e.g., https://mycompany.odoo.com).
• ODOO_API_KEY: Mandatory always. The Odoo API key (Odoo 14+, generate under Settings > Users > API Keys > New). An account password is not accepted. A key is per-user, scoped, and revocable on its own. Odoo 19 additionally requires a description and an expiry, max 3 months.
• ODOO_DB: Mandatory on Odoo Online (SaaS, *.odoo.com), optional elsewhere. On Odoo Online, the database-list endpoint is disabled. Discovery cannot find the name, and every tool call fails with an opaque "Error executing tool" without hinting that the database is the problem. With ODOO_DB set, the same config connects immediately. The SaaS database name is not the pretty subdomain — it carries a suffix, in the shape mycompany16-prod-12345678 — and you find it at /web/database/selector or in the Odoo.com account page. Elsewhere, it is discovered automatically when the instance serves exactly one database, and is required when it serves several.
• ODOO_USER: Never mandatory. Omitted, the client probes res.users for uid 1 to 59 and keeps the one the key answers for. This adds up to 59 extra round trips on the first call, and it fails outright if the key owner's uid is 60 or higher. Setting it removes that cost. It must be the login (e.g. jane@mycompany.com), and a wrong value makes Odoo's authenticate() return False rather than raise — which reads like a permission error.
• ODOO_MCP_MAX_LEVEL: Optional, default 3. The highest safety level this server may execute, 0 to 4. A value of 0 makes the server refuse every write, which is what you want when pointing an agent at live company data for reading. Refer to the Safety Layer section for the L0 to L5 table. An invalid value refuses startup. 5 is accepted but identical to 4.
• ODOO_MCP_PROTECTED_HOSTS: Comma-separated hosts this server refuses to write to (empty by default, no host is baked into the package). A listed host still allows reads. Writing to it needs ODOO_ALLOW_PROD_WRITE=yes as a deliberate override.

Safety Layer

Every write and action passes through a dynamic safety classifier before reaching Odoo. Operations are classified into levels L0 to L5:

Choosing the ceiling

ODOO_MCP_MAX_LEVEL sets the highest level this server may execute. Each value is cumulative, permitting its own level and everything below:

Two behaviours are worth knowing before you pick a number:

• 5 does not unlock L5. Both L5 variants are refused before the ceiling is ever read. L5_PRIVATE is refused because Odoo itself rejects every method starting with _, so no ceiling could deliver it; L5_UNKNOWN is refused because a method nobody classified has, by definition, unreviewed effects. The way to allow such a method is to add it to WRITE_L1/L3/L4 in safety_layer.py in code, reviewed, never through configuration.
• An invalid value refuses startup. ODOO_MCP_MAX_LEVEL="O" raises rather than falling back to the default, because the fallback is write-capable: a typo must not hand you a writing server you believed was read-only.

The ceiling is set out of band, by a human, and read from the process environment at startup. The model running against this server cannot raise it; when a call exceeds the ceiling the refusal names the level required, so the agent can explain what the operation would change and leave the decision to you.

Note that this is the authority of this server, not of the account. An agent with shell access can always bypass an MCP server by invoking Odoo directly. A limit that must hold regardless of the client belongs in the Odoo access rights of the user the API key belongs to, where the Odoo server enforces it.

Odoo Version Support

Odoo 14.0 is the absolute minimum supported version because this server authenticates using API keys only, which do not exist in Odoo 13 or earlier.

Two things changed between Odoo 16 and 17, and neither needs configuration:

• Discuss was renamed. mail.channel / mail.channel.member became discuss.channel / discuss.channel.member in 17. The server asks the instance which pair it has and uses that, so the four Discuss tools work on both generations.
• Subscriptions moved onto sale.order, which before 17 had no subscription_state field at all. On 16 that section is simply absent from instance_overview — an absence, not a failure.

API Key Generation Path

To generate an API key, log in to your Odoo instance and navigate to: Preferences / My Profile → Account Security → New API Key

Transport & Deprecation Note

The client automatically detects if the native JSON-2 API is available at /json/2/<model>/<method> (which uses Authorization: bearer <API_KEY>) and falls back to XML-RPC if it is not. Please note that XML-RPC and JSON-RPC are deprecated in Odoo 19 and scheduled for removal in Odoo 22.

Sources

• Odoo 14.0 External API Documentation (API keys introduction)
• Odoo 19.0 External API Documentation (JSON-2)
• Odoo 19.0 External RPC API Documentation (XML-RPC deprecation)
• Odoo Standard & Extended Support Policy (Support timelines)

Tools and Resources

The server exposes 19 tools and 2 resource types:

Tools