Skip to content

Odoo Tools: Introduction

MCP-Odoo-Tools is a Claude Code plugin that unifies access to Odoo in a single installation: an MCP server (main surface) and a fallback CLI. It works with Odoo Community, Enterprise and online (SaaS), from version 10 through 19, thanks to a compatibility layer that automatically resolves the model and field names that change between versions. Its skills and commands also load in Cowork and Claude chat, but the Odoo tools themselves run in Claude Code only (see Where it works).

Online/SaaS: requires a plan with external API access

External RPC access is only available on Odoo Online subscriptions with API access enabled (Custom plans). On plans without external API access the connection fails even with correct credentials: verify with odoo_version and see Troubleshooting on connection errors. On Odoo Online an API key is the only credential that works.

Start here

Install the plugin and run /odoo-tools:odoo-setup-mcp: the guided route for setup, training, use and deployment. No Odoo to practice with? /odoo-tools:deploy-local starts a local sandbox.

New in v1.6.0: one copy, the right copy, and the right place for each command

  • Install commands by surface: /plugin install inside Claude Code, or claude plugin install ... --scope user in a terminal. Install one copy only. See Installation.
  • odoo_version names the copy that answers (plugin block), and the guided route and /odoo-tools:odoo-doctor find a second copy or one older than 1.5.0 and stop there. See Two copies of odoo-tools.
  • Windows without python3: claude mcp list reports the server as Failed to connect with Connection closed, and nothing names Python. The fix is in Troubleshooting.
  • The app's not_started status: /odoo-tools:odoo-doctor and the guided route recognize the status not_started with the reason user_config_unsupported as the Cowork and Claude chat case: it is not a bug, and no update changes it. They send you to a local session of the Code tab or to Claude Code; Claude Code needs no administrator rights. See Troubleshooting.
  • The local sandbox comes with an API key for the plugin on Odoo 14.0 to 19.0. See Local deployment.
  • Still 28 tools. On Odoo 10 to 12, the policy also refuses the keys of an object passed positionally that are neither fields of the model nor allowed context keys, so the policy digest changes. See Permission policy.

New in v1.5.1: honest on every surface, with local diagnostics

  • Where Claude runs comes first. When the Odoo tools are not loaded, /odoo-tools:odoo-doctor runs no command, checks no Python and gives no Odoo-side advice: in Cowork and Claude chat it sends you to the Code tab of Claude Desktop or to Transgenia. The skills, commands and agents that use the Odoo tools start with the same check.
  • Local diagnostics and a support report. The server keeps a small, metadata-only record on your computer, and the doctor ends with a report with no keys, URLs, logins or record data that you can send to Transgenia. See Support.
  • A session-start hook that reads no plugin option and no credential, and a server that no longer reads ODOO_HTTP_BEARER. See Security.
  • Still 28 tools. The readonly, standard and builder profiles refuse a little more (the context rules also apply to an object passed positionally, which Odoo 10 to 12 take as the context), so the policy digest changes. See Permission policy.

New in v1.5.0: secure permissions by default

The MCP server applies a permission policy on top of the Odoo user's own rights. The default profile, standard, reads, creates, updates and runs business methods, but does not delete, make Studio-style changes, send email or SMS (internal notes are fine) or read stored secrets; it lists 25 of the 28 tools. Every call leaves one line in a local audit log. To keep the 1.4 behavior, set the Permission profile option to full.

It is built and maintained by Transgenia, registered partner of Anthropic (Registered tier). It is an independent open-source project with an MIT license; it is neither a certified nor a first-party product of Anthropic. It is listed in Anthropic's plugin directory, where each new version arrives once an Anthropic reviewer approves it, so the directory may offer an earlier version than the one this manual describes. Install one copy only, from Transgenia's marketplace (see Installation).

Where it works

Surface MCP server (the Odoo tools) Skills and commands Agents and hooks
Claude Code on your computer (CLI, VS Code, JetBrains, a local session of the Claude Desktop Code tab) Yes Yes Yes
Claude Code in a cloud session (Claude Desktop Code tab, claude.ai/code) No Yes Yes
Cowork (Claude Desktop) No Yes Yes
Claude chat (claude.ai web, desktop, mobile) No Yes No

The Odoo tools run as a local stdio MCP server (python3 3.9+) on the machine where Claude Code runs, and the connection options (URL, database, login, API key) are entered through Claude Code's plugin options (userConfig in plugin.json): Claude Code prompts for them when the plugin is enabled, or takes them with claude plugin configure.

Per Anthropic's plugin support matrix, Cowork does not prompt for option values and ignores an MCP server that references an option without a default (the URL, database, login and credentials of this plugin have none), and Claude chat ignores a plugin's local MCP server. In those apps the plugin still installs and its skills and commands still load, but they cannot reach Odoo without the tools. That is the app working as designed, not a broken install.

Claude Desktop names this case for this plugin's server with the status not_started and the reason user_config_unsupported: it is the same on macOS and Windows, it is not a fault of the plugin or the app, and no update of the plugin changes it.

Nothing is wrong with your account, your Odoo or your Python. Open a local session of the Code tab of Claude Desktop (or Claude Code in a terminal, VS Code or JetBrains): the plugin you installed on your Claude account appears there as a synced plugin when you sign in with the same account. Or ask Transgenia for assisted setup: dev@transgenia.org · WhatsApp +52 55 8034 0405.

A cloud session of Claude Code (the Code tab's cloud environment, or claude.ai/code) is a separate case: the plugin is synced from your account but its options are not. Claude Code saves them on the computer where you enter them (the API key and password in that computer's secure credential store), so the server does not start in the cloud. Use a local session.

Cowork and Claude chat do accept MCP connectors you add yourself: a remote MCP server reachable at an https URL or, in the Claude desktop app, a desktop extension. This plugin provides neither: its Odoo tools need the local server. If on claude.ai you see the odoo row labeled Runs in each session with an empty panel, see Troubleshooting.

What it solves

Odoo model and field names change between versions:

  • account.invoice was merged into account.move in v13 (a merge, not a rename: on v10-12 they coexist as invoices vs. journal entries; see Compatibility).
  • The analytic fields changed in v16 (analytic_account_id → analytic_distribution).
  • The package models changed in v19 (stock.quant.package → stock.package).
  • The name_get method is gone in v18 (read display_name instead).
  • Odoo Online gets changes early on its saas~N.M lines: uom_po_id is gone from saas~18.1, before 19.0.
  • The RPC API itself changes from v19: /xmlrpc and /jsonrpc are deprecated and Odoo 22 (and Odoo Online saas~21.1) remove them; their replacement is JSON-2, which the server uses automatically when an API key is set.

In addition, Enterprise includes models that Community does not have. For an AI agent, each of these differences is a silent point of failure: it calls the old name, the ERP responds with an error, and the agent cannot tell whether it is a permissions, network or version problem.

This plugin absorbs those differences behind a single stable tool surface, so you do not have to branch your code by version.

The two surfaces

Surface When to use it Requirements
MCP server (recommended) Normal use from Claude Code: 28 tools (6 of them for Odoo Online; 25 listed under the default profile standard) + full compatibility layer, over JSON-2, JSON-RPC or XML-RPC, with a permission policy and an audit log python3 3.9+ (standard library only; installs nothing)
Fallback CLI When you cannot run the MCP server, or for batch access from scripts Node.js 18+

Scope (public vs. private)

This is the public generic core: it talks to Odoo and nothing else. Since v1.5.0, a generic, declarative permission policy is part of the public core. Approval workflows, localization engines (for example, per-country electronic invoicing), backups, document AI and other client-specific engines are deliberately left out of this repository and offered as part of Transgenia's supervised implementations.

Next step

Continue with the Installation or jump straight to the guided Quickstart.

Implementation support

Need help connecting it to your Odoo or a custom AI/ERP integration? Transgenia offers AI and Odoo implementation services. Write to us at dev@transgenia.org.