Odoo Assistant

Singleflo for Odoo

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

Singleflo for Odoo is an independent project, not affiliated with, endorsed by or sponsored by Odoo S.A. Odoo is a trademark of Odoo S.A., named here only to say which software this server works with.

Quickstart

Install with your AI agent. If you already have an AI assistant on your computer — Hermes, Claude Code, Claude Desktop, Codex, Cursor, opencode, any of the hosts below — paste this prompt into it as one message:

Please install "Singleflo for Odoo" (the MCP server `odoo-assistant`) so that you can work with my Odoo.

Open and follow, step by step, the instructions written for you at: https://raw.githubusercontent.com/singleflo/odoo-assistant-mcp/main/docs/INSTALL-WITH-YOUR-AGENT.md I am not technical. Talk to me in English, give me one simple step at a time and wait for my answer, and do all the technical work yourself. When you need the Odoo API key, guide me through creating it screen by screen. Never ask me for my Odoo password. At the end, check that you can read my Odoo and tell me what you set up.

The same prompt in Italian, Spanish and Czech is in docs/INSTALL-PROMPT.md. The page it links is written for the agent rather than for you: it asks you for the Odoo address, walks you through creating the API key, finds the database name on Odoo Online, installs uv, writes the configuration file its own host reads, and verifies the connection. In Claude.ai or ChatGPT, which cannot install anything, it guides you to the hosted connection instead. The manual route is below.

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

### Don't have an API key yet?

[How to create an Odoo API key →](docs/api-key.md) — seven steps, with a

screenshot of each.

In short: *avatar → Preferences → Account Security → New API Key*. It is

never your account password, it belongs to one Odoo user and carries exactly

that user's permissions, and Odoo shows its value exactly once.

• 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+ — see the box above, or docs/api-key.md). 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_ALLOW: Optional, default * — every method the deny list does not refuse. The single value none makes the server read-only, which is what you want when pointing an agent at live company data for reading. Anything else is a comma-separated list of method names. See "What the agent may do" below.
• ODOO_MCP_DENY: Optional. Unset, it is the default deny list — unlink, archive, action_cancel, button_cancel, action_reverse, action_draft, mailing.mailing:action_send. A value you set replaces that list entirely. See "What the agent may do" below.
• ODOO_MCP_ALLOW_UNLINK: Optional, off by default. yes, true or 1 (any case) grants unlink; no entry on either list can. See "What the agent may do" below.
• ODOO_MCP_DATA_DIR: Optional. Where this server keeps everything it writes, the instance profiles included. It defaults to the platform's own data directory — %LOCALAPPDATA%\odoo-assistant on Windows, ~/Library/Application Support/odoo-assistant on macOS, and $XDG_DATA_HOME/odoo-assistant (else ~/.local/share/odoo-assistant) elsewhere.

What the agent may do

Every write and every action passes a gate before it reaches Odoo. The gate judges a call by its METHOD NAME against two lists you own, in the host configuration file, and reads both from the process environment at call time:

• ODOO_MCP_ALLOW — what may run. Unset or empty means *: every method the deny list does not refuse. The single value none makes the server read-only.
• ODOO_MCP_DENY — what may not. Unset or empty means the default list: unlink, archive, action_cancel, button_cancel, action_reverse, action_draft, mailing.mailing:action_send. A value you set replaces that list entirely rather than extending it, so the refusals in force are exactly the names in your own file — ODOO_MCP_DENY=unlink is how you re-admit action_cancel.

An entry is either method, which matches that method on every model, or model:method, which matches it on one. Matching is exact string equality — no prefix, no substring, so action_send never matches action_send_and_print and action_cancel never matches button_cancel. A human read and approved those exact names, and a looser match would let lookalikes through that nobody saw. Deny is checked before allow, so a name on both lists refuses.

Model qualification is what the measured case needs. On one live instance 31 models answer to action_send, and only the Evolution wizards should — the one on mailing.mailing can email an entire customer base in a single call. That is why the default deny list spells that entry mailing.mailing:action_send and leaves action_send working everywhere else.

Four rules sit outside the lists:

• `unlink` is decided before both of them. No value of ODOO_MCP_ALLOW or ODOO_MCP_DENY can ever grant deletion; only ODOO_MCP_ALLOW_UNLINK does — yes, true or 1, any case. Deletion is the one action that cannot be undone, and a name in a comma-separated list must never be enough to grant it.
• `archive` is a virtual name. Both action_archive and a write carrying active: False carry it into the lists, so denying archive refuses hiding records however they are spelled.
• Private methods are always refused, whatever the lists say. Odoo itself rejects every method starting with _, so no list could deliver one.
• Reads never pass through either list, because a read has no effect for a list to govern. The account.move structural guard is untouched by any of this and still applies to them: a query mixing invoices, bills and journal entries is refused whatever the lists hold, because a meaningless read is its own hazard.

The lists are set out of band, by a human, and the model running against this server cannot change them. When the gate refuses, the reason names the call, the entry that decided it and the variable that would change the answer, so the agent can explain what the operation would have changed 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.

Database and login: when you must set them

Only ODOO_BASE_URL and ODOO_API_KEY are required everywhere. ODOO_DB and ODOO_USER are discovered, and whether that discovery can succeed depends on how your instance is hosted.

The database is looked for in two steps, in this order: list() on /xmlrpc/db, then a /web/session/get_session_info POST, which needs no credentials and still reports the database name when list_db = False hides the first one. The login is never asked for — an API key belongs to exactly one user, and execute_kw accepts it only with that user's uid, so the client finds the owner by probing res.users for uid 1 through 59.

ODOO_USER is never mandatory by itself, on any hosting. Setting it saves up to 59 discovery round trips on the first call of a session, and it becomes required when the API key owner's uid is 60 or higher, because discovery only probes uid 1 to 59. It must be the login (e.g. jane@mycompany.com), and a wrong value is quiet in a way that misleads: Odoo's authenticate() returns False for an unknown login rather than raising, so a typo reads like a permission error and not like a typo.

By Odoo version

Odoo 14 through 18 behave identically here. XML-RPC carries the database name in every execute_kw call, so the client must know it before it can authenticate at all — which is exactly why discovery exists.

Odoo 19 adds the JSON-2 API, which selects the database with an X-Odoo-Database HTTP header. The header table on Odoo's own page lists it as optional, and the page's *Database* section is specific about when it stops being: it is "required when a single Odoo server hosts multiple databases and the dbfilter wasn't configured to use the Host header", or, as the same page puts it elsewhere, the database "must only be provided (via the X-Odoo-Database HTTP header) on systems where there are multiple databases available fo