Skip to content

Troubleshooting and FAQ

Question-form headings so you can find your case quickly.

New in v1.6.0

New or changed cases: two copies of odoo-tools (with odoo_version without a policy block), a /plugin command typed in PowerShell, Failed to connect on Windows without python3, the context passed positionally, whose keys that are not fields of the model are now checked on Odoo 10 to 12 too, a sandbox that never started because of a password that started with "-", and the app's not_started status in Cowork and Claude chat, with the local session of the Code tab and who needs administrator rights.

New in v1.5.1

New or changed cases: the session-start notice about Cowork and Claude chat (it replaces the missing-options notice), the notice of the policy locked at the last start, the context passed positionally and the support report.

New in v1.5.0

New cases from the permission policy: a policy refusal, the tools that no longer appear, the locked policy, how to go back to the 1.4 behavior, the withheld fields, outbound email, the default_ context keys and the audit log. Also, odoo_report returns an error.

New in v1.4.1

New cases: the empty "Runs in each session" panel, the missing-options notice (replaced in v1.5.1) and the hook error on Windows without Git Bash.

New in v1.4.0

New cases: the Odoo 19 transport_notice, the rate limit (HTTP 429), imports refused on XML-RPC and report PDFs.

A call is refused with "the odoo-tools permission policy refuses"

Since v1.5.0, the permission policy decides each call on top of the Odoo user's own rights. The refusal names the operation, the model, the profile and the rule (for example rule profile:standard or rule tier:security), and says what changes it. If it ends with Nothing was sent to Odoo., it was decided before sign-in; if it ends with The call was stopped before Odoo ran it, the check of the actual call stopped it, and Odoo changed nothing.

  • It is final for the agent: Claude explains it to you and does not look for another way (another tool, the fallback CLI or the shell). You decide.
  • To change it: choose another profile in /plugin → odoo-tools → Configure options → Permission profile, or add a rule to your policy file, and reconnect the server (/mcp).
  • To find out why before calling, check the decision offline: python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-policy "" --profile standard --explain res.partner:unlink.
  • odoo_access_check shows side by side what Odoo allows and what the policy allows.
  • A refusal with rule envelope is a bug in odoo-tools, not a policy decision: report it to dev@transgenia.org.

Under the default profile standard, those three tools are not listed (standard lists 25 of the 28). To delete, archive with odoo_write {"active": false}; for fields and automations on a sandbox or on staging, choose the builder profile; for everything the Odoo user may do, full. Under the readonly profile, or with Read-only mode on, none of the 9 write tools is listed. See Tools each profile lists.

Only odoo_version shows up: the policy is locked

An unknown profile, a relative policy file path or an invalid file lock the server: only odoo_version is listed, and it returns the policy block with error and error_code without contacting Odoo; every other tool is refused. In Claude Code, the session-start hook reads it from the local diagnostics of the last server start and tells you at most once a day, with a message such as odoo-tools: the permission policy locked the Odoo tools at the last server start (E15). ...; ask Claude to call odoo_version for the reason.

  1. Check the file offline: python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-policy /absolute/path/policy.json (it exits with 1 and names the error, for example E15 when an opening of a sensitive model has no reason).
  2. Fix the file, or the Permission profile / Permission policy file options (the path must be absolute).
  3. Reconnect the server with /mcp.

The table of codes E1 to E20, W1 to W7 and W10 is in Loading errors and warnings.

How do I go back to the 1.4 behavior?

Set Permission profile to full (ODOO_POLICY=full in a container or in standalone mode) and reconnect the server. full allows everything the Odoo user may do, except creating, changing or revoking API keys and uninstalling modules. To enforce those two refusals, full also refuses a call whose arguments it cannot read with certainty (rule shape: pass the arguments by name) or whose related models it cannot look up with fields_get (rule unverified). See Profiles.

A result carries policy_withheld_fields

Outside full, credential-like fields (passwords, tokens, keys, such as l10n_mx_edi_pac_password or signup_token) are removed from what reads return, and the result names them in policy_withheld_fields so that nothing disappears silently. Asking for them in a field list, a filter, a grouping or an order is refused. A policy file can release an exact field with fields.allow and a reason, or withhold more with fields.withhold. See Credential-like fields.

message_post is refused under standard

The methods that send data out (message_post to contacts, message_subscribe, send_mail and others) are refused under readonly, standard and builder. An internal note does run: message_post with subtype_xmlid "mail.mt_note" (Odoo 13+; subtype on 10-12), without partner_ids. To reply to customers from the chatter, use full, or a policy file entry that names the model exactly with "call": ["message_post"] and a reason (see the sales-team.json example in Examples).

A wizard is refused because of a default_ context key

Behavior in v1.5.0

Under readonly, standard and builder, a default_<field> context key whose value is a list or an object is refused (rule context) before anything is sent to Odoo. This happens, for example, to the manufacturing backorder wizard created through odoo_execute with its action's default_mrp_production_ids and default_mrp_production_backorder_line_ids keys. Pass those values in the record's values (mrp_production_ids: [(6, 0, [id])] and the lines with (0, 0, {...})), or pick_ids: [(4, id)] for the stock backorder wizard. See Context keys.

The context keys that the stock and manufacturing validation wizards need (button_validate_picking_ids, skip_backorder, and so on), the validate_analytic of the invoice Post button and the web client's uid are allowed.

A call is refused because of a context passed positionally

Odoo 10 to 12 also take a call's context from the positional argument that follows the method's parameters. Since v1.5.1, the policy reads that argument as a context and applies the context rules to it: at Layer A on every series, before the version is known, and on 10 to 12 again in the guarded session. With a method the policy does not know, such as action_confirm, it checks the default_<field> keys of every object passed positionally and, since v1.6.0, on Odoo 10 to 12 its other keys too, with the model's fields: a key that is a field of the model is checked as one of the method's values, an allowed context key passes, and any other key, such as tracking_disable, is refused (rule context). When the model's fields cannot be read, the call is refused (rule unverified). The refusal names the key, never its value.

Pass the context by name, in kwargs ("kwargs": {"context": {...}}), and the method's other arguments by name too, or put the values in the record's values. What remains on Odoo 10 to 12, a context key with the name of one of the model's fields, is in known limit 10.

How do I check the audit log?

The daily files are in the plugin's data folder (~/.claude/plugins/data/…/audit/odoo-tools-audit-YYYY-MM-DD.jsonl). To check the hash chain of a file:

python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --verify-audit FILE

It exits with 0 when the chain holds, with 1 at the first line that was edited, reordered or inserted (or an incomplete final line), and with 2 when it cannot read the file. See Audit trail.

Two copies of odoo-tools, or one older than 1.5.0

The signs:

  • odoo_version answers without a policy block (and without a note): an odoo-tools older than 1.5.0 answered, with no permission policy, profile or audit log. The guided route and /odoo-tools:odoo-doctor stop there, before any write.
  • Configure options shows no Permission profile: the dialog edits a copy older than 1.5.0.
  • The plugin's Errors tab says Plugin option "odoo_url" isn't set for a copy you never configured. That message comes from Claude Code, not from odoo-tools: the copy it names (shown in claude plugin list) has no saved options.

It is usually a second copy: for example one from the Claude plugin directory in a project folder, which can be older (the directory publishes a version after Anthropic reviews it), and one from Transgenia's marketplace for your user. Then the options you save can go to one copy while the tools of the other answer.

  1. Inside Claude Code, run /odoo-tools:odoo-doctor: it names the copy to keep and prints the exact commands that leave one current copy. Since v1.6.0, odoo_version names the copy that answers (plugin.copy).
  2. Run those commands in a terminal (PowerShell, Terminal or bash), not as /plugin commands: a cd to the project folder and claude plugin uninstall <id> --scope <scope> or, for an old copy from Transgenia's marketplace, claude plugin marketplace update transgenia-odoo-tools and claude plugin update odoo-tools@transgenia-odoo-tools --scope <scope>. Without the doctor, claude plugin list shows every copy with its version and scope.
  3. Restart Claude Code (or run /reload-plugins inside it) and call odoo_version again: the answer carries plugin and policy.

The directory's copy is odoo-tools@anthropic-plugin-directory; there is no odoo-tools@claude-plugins-official. The two checks and how to read their output: Two copies of odoo-tools.

PowerShell does not recognize /plugin or claude

A /plugin command is typed inside a Claude Code session, never in PowerShell: typed in the terminal, it fails with a "not recognized" error. In a terminal, the form is claude plugin:

claude plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online --scope user

If claude is not recognized either right after you install Claude Code, open a new PowerShell window: a window opened before the install does not see the new PATH. Claude Code's native installer puts claude.exe in %USERPROFILE%\.local\bin. The same happens after you install Git or Python (where.exe git finds nothing in the old window): open a new window and restart Claude Code. See Installation.

The Odoo tools do not appear (empty "Runs in each session" panel)

The usual symptom, in Cowork or on claude.ai: the plugin installs and shows as on, its Connectors tab lists the odoo row labeled Runs in each session, and opening that row shows an empty panel with no fields to fill in. On claude.ai on the web, the plugin's three-dot menu offers actions such as remove, edit with Claude or duplicate, and no place for the connection options. It is not a broken install, and nothing is wrong with your account, your Odoo or your Python. That row is the plugin's local MCP server: Anthropic's docs say that on the web the Connectors tab marks a local MCP server that way while chat does not start it, and there is no form because those apps do not prompt for plugin options. Per Anthropic's plugin support matrix, Cowork ignores an MCP server whose required options have no default, and Claude chat ignores a plugin's local MCP server. The skills and commands do load, but without the tools they cannot reach Odoo. If the app shows the plugin's server with the status not_started and the reason user_config_unsupported, it is this same case (see below).

  1. Use Claude Code on your computer (terminal, VS Code or JetBrains, or a local session of the Code tab of Claude Desktop). A plugin installed on your Claude account appears there as a synced plugin at the next session start when you sign in to Claude Code (2.1.273 or later) with that claude.ai account; if it does not show, run /reload-plugins or install it with the commands in Installation. No administrator rights are needed: Claude Code's native installer puts it in your home folder (~/.local/bin/claude on macOS and Linux), and on Windows Anthropic's guide says you do not need to run it as Administrator. On a Team or Enterprise plan your organization decides which plugins you get and whether the Code tab offers local sessions (when it does not, the entry for your computer is grayed out, with the tooltip Disabled by your organization).
  2. Enter the options there: /plugin configure <id> in a session, or /plugin → odoo-tools → Configure options (VS Code: the gear icon on the plugin's row). <id> is the full name@marketplace id that claude plugin list shows (for example odoo-tools@synced). On a headless machine (Claude Code 2.1.285 or later), use claude plugin configure <id> --json and --values-stdin (see Installation) and restart Claude Code.
  3. No Claude Code on that machine? In Cowork, the fallback CLI (/odoo-tools:odoo-setup-cli) can work when the session can run Node, reach your Odoo, and you can edit the CLI's .env yourself; use a dedicated, least-privilege, short-lived API key. Claude chat has no safe place to enter the key: use Claude Code. (On Claude Code without Python, use the container mode of /odoo-tools:deploy-local.)
  4. Still blocked? Run /odoo-tools:odoo-doctor: it ends with a support report you can send to Transgenia, which also offers assisted setup (see Support). Transgenia never asks for your API key or password in a chat or by email.

Cowork and Claude chat do accept MCP connectors you add yourself (a remote MCP server by https URL, or a desktop extension in the Claude desktop app), but this plugin provides neither: its tools need the local server.

The app shows not_started with the reason user_config_unsupported

The Claude app can report this plugin's server with the status not_started and the reason user_config_unsupported. It is the Cowork and Claude chat case of Anthropic's plugin support matrix: Cowork does not prompt for plugin options and ignores a local MCP server whose options have no default, and Claude chat ignores a plugin's local MCP server. It is expected, on macOS and Windows alike: it is not a fault of the plugin or the app, and no update of the plugin changes it. /odoo-tools:odoo-doctor recognizes it and puts the status in its support report as the app showed it, with the app's version.

The way out is a local session of the Code tab of Claude Desktop, or Claude Code on your computer (terminal, VS Code or JetBrains), with the steps above. A cloud session of the Code tab (or claude.ai/code) does not work: the plugin is synced from your account but its options are not, because Claude Code saves them on the computer where you entered them (the API key and password in that computer's secure credential store), so the server does not start in the cloud.

Who needs administrator rights:

  • Not Claude Code: its native installer puts it in your home folder (~/.local/bin/claude on macOS and Linux), and on Windows Anthropic's guide says you do not need to run it as Administrator.
  • macOS: python3 comes with Apple's Command Line Tools (xcode-select --install). If your Mac asks for an administrator to install them and you are not one, your IT team can install them, or ask Transgenia for assisted setup.
  • Team or Enterprise plans: your organization decides which plugins you get and whether the Code tab offers local sessions. When it does not, the entry for your computer is grayed out, with the tooltip Disabled by your organization.

Looking for an update does not change this case. The Claude plugin directory publishes a version only after Anthropic reviews it, so checking for updates in the Claude apps finds no newer version until then; and in Cowork and Claude chat no version runs the Odoo tools.

At session start: "In Cowork and Claude chat this plugin's Odoo tools do not run"

Since v1.5.1, the plugin's session-start hook (hooks/session_start.py, which replaces hooks/check_options.py) checks the MCP server's local diagnostics. When the last 14 days record neither a successful connection to Odoo nor a server start with every connection setting (URL, database, login and an API key or password), it shows you this notice when a new session starts, at most once a day:

odoo-tools: In Cowork and Claude chat this plugin's Odoo tools do not run, whatever Python or options. Open a local session of the Code tab of Claude Desktop (the plugin is synced there when you sign in with the same account) or Claude Code, or ask for assisted setup by Transgenia: dev@transgenia.org, WhatsApp +52 55 8034 0405. In Claude Code, set the connection in /plugin > odoo-tools > Configure options. /odoo-tools:odoo-doctor diagnoses.

At every session start it also tells Claude the same: that nothing is wrong with your account, your Odoo or your Python, that no update of the plugin changes this case, and to offer you, in this order, a local session of the Code tab of Claude Desktop or Claude Code, and assisted setup by Transgenia; then where the options are set in Claude Code, and the doctor. It ends with an odoo-tools session diagnostics: line that /odoo-tools:odoo-doctor uses for its support report.

On the first session after you install or upgrade the plugin, when there is no hook record yet, the notice goes to Claude only, because that session's server may not have written its start yet; the same happens wherever the hook has no plugin data folder to keep the notice to once a day.

  • In Cowork or Claude chat: the Odoo tools do not run there. Open a local session of the Code tab of Claude Desktop (or Claude Code), where the plugin appears as a synced plugin when you sign in with the same account, or ask Transgenia for assisted setup (see Support).
  • In Claude Code: enter the URL, database, login and API key in /plugin → odoo-tools → Configure options and restart Claude. The notice stops once the diagnostics record a server start with every connection setting or a successful connection.
  • The hook reads no plugin option and no credential: only the plugin's data folder (the server's diagnostics) and the name of the Claude app that started the session. See Security.
  • If you reach Odoo through another Odoo connector, separate from this plugin, the notice does not apply.
  • With the container mode of /odoo-tools:deploy-local, a marker in the plugin's data folder silences it (see Local deployment).

Windows: SessionStart hook error at session start

The plugin's session-start hooks are shell commands and need Git for Windows (Git Bash). Without it, Claude Code runs them in PowerShell, where they fail with a SessionStart hook error. Install Git for Windows; if you already have it and Claude Code does not find it, set CLAUDE_CODE_GIT_BASH_PATH to the Git Bash path. The MCP server is not affected: the Odoo tools keep working, only the session-start notices are missing.

Windows: claude mcp list says Failed to connect with Connection closed

It is the sign of a missing python3 command: the python.org installer provides only python.exe and py.exe, Claude Code starts the plugin's server with python3, and nothing in the message names Python. Put a python3.exe next to python.exe with a hard link, in PowerShell:

$python = (Get-Command python -ErrorAction Stop).Source
New-Item -ItemType HardLink -Path (Join-Path (Split-Path $python) "python3.exe") -Target $python
  • It needs write access to the Python folder: for an installation under C:\Program Files, run PowerShell as administrator.
  • If Get-Command python finds nothing, or a file under WindowsApps, Python is not on PATH: run the python.org installer again and select "Add python.exe to PATH", or install the Microsoft Store Python, which provides python3.exe.

Then restart Claude Code. CI checks this fix on Windows (windows-launch.yml, with Claude Code 2.1.314): with the hard link, claude mcp list shows the server connected; without python3.exe, it shows Failed to connect with Connection closed. More cases in python3 is not found or is too old.

Do API keys work over /jsonrpc on Odoo 17 or higher?

Yes. Odoo accepts API keys on /jsonrpc exactly as on XML-RPC: both endpoints go through the same dispatch_rpc (Odoo 14 to 19), and this was checked live on an Odoo 18.0. If a proxy or gateway in front of Odoo blocks or alters /jsonrpc, the auto transport falls back to XML-RPC (it pins XML-RPC after the first fallback and warns once). To force it, set the Transport preference plugin option to xmlrpc (in standalone mode: ODOO_TRANSPORT_PREF=xmlrpc). On Odoo saas~18.4 / 19.0+ with an API key, auto tries JSON-2 first (see Compatibility).

If the key fails on both paths, the key itself is the problem: check that it has not expired or been revoked, and that the Odoo login is the one of the user who created it.

XML-RPC and JSON-RPC are deprecated from Odoo 19

Odoo 19 deprecates /xmlrpc, /xmlrpc/2 and /jsonrpc and removes them in Odoo 22 and in Odoo Online saas~21.1; the replacement is the JSON-2 API, which the plugin uses since v1.4.0 when an API key is set. The legacy endpoints work on every version the plugin supports (10 to 19).

odoo_version returns a transport_notice on Odoo 19

The connection uses the deprecated /xmlrpc or /jsonrpc endpoints on Odoo 19+, and every call logs a warning in the Odoo log. The notice carries its own fix; usually it is one of these:

  • create an API key (Preferences → Account Security) and put it in the plugin's Odoo API key option (JSON-2 does not accept a password);
  • remove user:pass@ from the Odoo URL (that basic auth takes the Authorization header JSON-2 needs);
  • set Transport preference back to auto.

From Odoo 22 / saas~21.1 a password-only connection stops working (ConfigError).

I get "database not found"

The database name is incorrect. Check it in Settings → Database or in the login URL. The Odoo database plugin option (or ODOO_DB in standalone mode) must match exactly.

My Odoo Online/SaaS does not connect with correct credentials

External RPC access only exists on subscriptions with API access enabled (Custom plans). On plans without external API access you will see connection/authentication errors even with a correct user and key: confirm your plan in your Odoo panel and verify with odoo_version.

  • On Odoo Online an API key is the only credential that works: users sign in through odoo.com, often with 2FA.
  • From Odoo 18 API keys expire: a user who is not an administrator gets at most 1 day, unless one of their groups allows longer. If the connection stopped working from one day to the next, create a new key. odoo_online_profile shows when each key expires (names and dates only).

A field appears in dropped_fields and not in the result

That field does not exist in the target version. This is the expected behavior: instead of failing the whole query, the server drops the unavailable field and reports it. Check the Compatibility table for the equivalent modern name (e.g. analytic_account_id → analytic_distribution in v16).

I get a CompatError about an Enterprise model

You are querying an Enterprise-exclusive model (e.g. helpdesk.ticket, sign.request) against an instance detected as Community. Runtime module probing is the authority: if the module is not installed, the model is not available.

Do I need an API key or can I use a password?

  • Odoo ≥ 14: use an API key (recommended): the Odoo API key plugin option (ODOO_API_KEY in standalone mode).
  • Odoo < 14: there are no API keys; use the Odoo password option (ODOO_PASSWORD in standalone mode).

Set one of the two.

I upgraded from v1.0.0 and the plugin no longer connects

Since v1.1.0 the plugin no longer reads ODOO_* variables from your shell: it uses plugin options. Enter your values once in /plugin → odoo-tools → Configure options and restart Claude. You can then remove the export ODOO_* lines from your shell profile (they remain valid only for the standalone server). See Installation.

python3 is not found or is too old

Since v1.2.0 the plugin launches the MCP server with python3 (no longer with uv) and needs Python 3.9 or newer, with no extra packages. If the odoo server does not start (or shows as failed in /mcp), run python3 --version in a terminal:

  • The command does not exist: install Python 3.9+. On macOS, xcode-select --install (Command Line Tools) brings python3; if your Mac asks for an administrator to install them and you are not one, your IT team can install them, or ask Transgenia for assisted setup. On Linux, install your distribution's python3 package.
  • Version older than 3.9: the server exits with odoo-tools: Python 3.9 or newer is required (found X.Y.Z). Upgrade Python or put a newer one earlier on the PATH you start Claude from.
  • Windows: the command must be named python3. The Microsoft Store Python provides python3.exe; the python.org installers only create python.exe and the py.exe launcher, so python3 does not exist, and claude mcp list reports the server as Failed to connect with Connection closed. Install the Microsoft Store Python or put a python3.exe on the PATH (a copy of or hard link to python.exe in the same folder; the command is in Windows: claude mcp list says Failed to connect). A PowerShell or doskey alias is not enough: Claude Code starts the command directly, not through your shell. If typing python3 opens the Microsoft Store instead of printing a version, that is the Windows app execution alias: install the Microsoft Store Python, or turn off the python3.exe entry under App execution aliases (Windows Settings) so your own python3.exe is found.

Then restart Claude so the MCP server is launched with that python3. If you cannot install Python, use the Fallback CLI.

At session start, the plugin's first hook also tells you when python3 is not runnable (odoo-tools: python3 is not runnable on this computer. ...). In Cowork and Claude chat the Odoo tools do not run with or without Python: there the fix is not to install it (see Does it work in Cowork or Claude chat?).

TLS certificate error (CERTIFICATE_VERIFY_FAILED)

Since v1.2.0 both transports verify your Odoo's certificate against the system trust store (honoring SSL_CERT_FILE) and, if the optional certifi package is installed for that python3, against its CA bundle too. When your Python has no CA file of its own (e.g. python.org macOS builds before running Install Certificates.command), the server loads the operating system's CA bundle automatically. If it still fails (e.g. your Odoo uses an internal CA), add that CA to the system store, point SSL_CERT_FILE at a CA bundle or install certifi. Do not disable TLS verification.

I get Input validation error: ...

The tool received wrong or misnamed arguments: a required one is missing, one is unknown or misspelled, or its type does not match. Since v1.2.0 the server validates arguments against each tool's schema and refuses the call before touching Odoo. Check names and types in the Tools reference and try again.

A transport error ends in "may or may not have been applied in Odoo; check before retrying"

The call (a create, a write or any other execute_kw) may have been applied in Odoo even though no reply arrived: it timed out, or Odoo (or a proxy in front of it) answered HTTP 5xx. In auto mode the server no longer replays it over XML-RPC, so it cannot create duplicates. Before retrying, check in Odoo whether the record was created or changed.

Long calls fail with a timeout

Each Odoo call waits at most ODOO_TIMEOUT seconds (120 by default, Odoo's default limit_time_real). For longer operations (reports, large exports), raise the Request timeout plugin option (5 to 3600 s; in standalone mode: ODOO_TIMEOUT) and restart Claude. If the call that timed out was a write, see the previous entry first.

I get HTTP 429 or "retry later"

Odoo (above all Odoo Online, with about 1 call per second) rate-limited the calls. Since v1.4.0 an HTTP 429 never switches transport: reads wait for what Retry-After says (at most 30 s, 3 tries) and retry on the same transport; writes are reported so you can retry them later. Pace bulk work, with no parallel calls, and use odoo_import (at most 500 rows per call) instead of one odoo_create per record.

odoo_import or odoo_import_preview is refused on XML-RPC

The import tools run only over JSON-RPC or JSON-2: Odoo's XML-RPC cannot return the empty values an import result carries, and a saved import could be reported as an error. A session on XML-RPC (Odoo 10-11, or Transport preference set to xmlrpc) refuses them before sending anything. Go back to auto or use jsonrpc/json2. odoo_import_preview needs Odoo 16+ and odoo_import Odoo 12+. With Read-only mode on, or under the readonly profile, both are no longer listed and are refused.

odoo_report returns an error

Since v1.5.0, odoo_report is deprecated and always returns an error without calling Odoo: it used the private method _render_qweb_pdf, which Odoo refuses over RPC on every version, so it never worked. It is removed in 2.0.0. Use odoo_record_documents: it lists the record's attachments and returns the documents Odoo already stored, such as an invoice PDF generated when it was sent or printed (flagged from Odoo 17), up to 5 MiB. See the Tools reference.

Can I use an ODOO_URL with user:pass@?

Yes. If your Odoo sits behind HTTP basic auth, put the credentials in the URL (https://user:pass@odoo.example.com, in the Odoo URL option or in ODOO_URL). JSON-RPC sends them as an Authorization header, and the password is never echoed in errors or logs. Keep in mind that Odoo URL is not a sensitive option: that password is stored in the plugin settings, not in the secure credential store. JSON-2 needs that same header for its API key, so such a URL stays on the legacy endpoints (with a transport_notice on Odoo 19+) and cannot work from Odoo 22 / saas~21.1, where those endpoints no longer exist.

The Odoo tools appear twice

You have both the plugin's own server and the odoo-tools-docker container server from /odoo-tools:deploy-local configured. Keep one: to remove the container, claude mcp remove odoo-tools-docker, and remove its marker too with rm "${CLAUDE_PLUGIN_DATA}/diagnostics/container-mode", so that the session-start hook speaks again if the plugin's server does not reach Odoo.

I don't have Python, only Node

Use the Fallback CLI: /odoo-tools:odoo-setup-cli (Node.js 18+). If you have Docker, you can also run the MCP server as a container: /odoo-tools:deploy-local, container mode (Local deployment).

The local sandbox does not start

  • Docker with Compose is required: install Docker Desktop or Docker Engine with the compose plugin.
  • the Docker engine is not running: open Docker Desktop (or sudo systemctl start docker) and retry.
  • Port 8069 ... is already in use: another Odoo uses the port; run again with --port 8070 and use that URL in the plugin options.
  • Odoo did not answer ...: check sandbox logs; on slow machines the first run takes longer (raise --timeout).
  • already holds an Odoo 18.0 database: you changed version; run sandbox destroy --yes, or --dir for another folder.
  • This sandbox was created with a database password that the Odoo image cannot use: before 1.6.0, about one new sandbox in 64 got a database password that starts with "-". From 11.0, the Odoo image passes it to wait-for-psql.py on its command line, which read it as an option, so the Odoo container restarted forever and sandbox up timed out with Odoo did not answer. This message comes only for a sandbox of Odoo 11.0 or later that never started: run sandbox destroy --yes, then sandbox up again, and nothing is lost. On 10.0, the image passes that password to Odoo, which takes it, and a sandbox that already worked is never refused. Since 1.6.0 no generated password starts with "-", and the message shows no part of the password.

The error mentions /odoo-tools:odoo-setup-mcp and Transgenia

Since v1.3.0, configuration, authentication and transport errors end with the command that fixes them and the official support channels. Follow the guided route; if it still fails, write to dev@transgenia.org or on WhatsApp to +52 55 8034 0405.

What do I send to support when something fails?

Run /odoo-tools:odoo-doctor: it first checks whether the Odoo tools run where you are, then the connection, and it ends with a support report with no API keys, passwords, URLs, logins or record data. Send it to dev@transgenia.org or on WhatsApp to +52 55 8034 0405. See The support report.

How do I verify that everything is set up correctly?

Run /odoo-doctor or call odoo_version. A response with version, edition, deployment and transport confirms the end-to-end connection. Since v1.4.0 odoo_version signs in first, so a wrong API key or password no longer passes as a working connection. Since v1.6.0 the response also carries plugin, with the version and the copy that answered; without a policy block, a copy older than 1.5.0 answered (see Two copies of odoo-tools). See Connection and discovery.

Is my company's data sent to Anthropic?

Two paths: the MCP server talks directly to your Odoo (Transgenia does not proxy, store or see your data), but tool results returned to the AI agent are sent to the model provider (e.g. Anthropic for Claude) for processing. See Security and Privacy.

Does it work in Cowork or Claude chat?

The plugin's skills and commands do load there, but the Odoo tools do not: they run as a local MCP server in Claude Code only. Nothing is wrong with your account, your Odoo or your Python: open a local session of the Code tab of Claude Desktop, where the plugin is synced to the same account, or ask Transgenia for assisted setup. See Where it works, the empty panel case and the not_started status.

Does it work with agents other than Claude?

Yes: with any client that implements the MCP protocol. Claude Code is the reference environment the plugin is packaged for.