You've been hearing for months that "AI can talk to your ERP." What nobody explains is that Odoo renamed dozens of models between version 12 and 19, and that an MCP server that doesn't handle this at runtime will silently mislead the agent. Here is what we built to solve it, why we published it under MIT, and what we intentionally left out.
account.invoice → account.move in v13). It ships as a Claude Code plugin, installs via uvx, and the source code is published on GitHub under the MIT license.
The real problem: Odoo model names change across versions
Odoo is the most widely adopted ERP among SMEs in Latin America, but it comes with a detail that consultants rarely mention before the contract is signed: every major version reorganizes or renames models and fields. The most well-known example is account.invoice, which became account.move in Odoo 13. There are dozens of similar changes between versions 10 and 19.
For a human who knows the history, this is a learning curve. For an AI agent, it is a silent failure point: the agent calls the old model name with confidence, the ERP returns an error that looks like a permissions or network issue, and the agent cannot distinguish a credentials problem from a nomenclature problem.
We could have built an MCP server that assumes Odoo 19 and called it done. But that would exclude thousands of businesses running perfectly functional version 14, 16 or 17 deployments with no reason to migrate just because AI arrived.
What MCP-Odoo-Tools is
MCP-Odoo-Tools is a Python server that implements the Model Context Protocol (MCP, published by Anthropic as an open standard) on top of Odoo. The source code is published on GitHub under the MIT license. It is a clean-room implementation (not derived from any AGPL fork) and it ships packaged as a Claude Code plugin.
What distinguishes it from a basic Odoo integration:
Cross-version compatibility layer. A declarative map covers model and field name differences from Odoo 10 through 19. When an agent requests invoice data, the layer determines at runtime whether the connected instance uses account.invoice or account.move, without the agent or the operator needing to know the version in advance.
Automatic version and edition detection. The server identifies the exact Odoo version (CE, EE or online), edition and deployment mode at connection time. That information feeds the compatibility layer and the transport selector.
Dual transport with automatic fallback. The server uses XML-RPC as the primary protocol and JSON-RPC as a fallback. The fallback matters: starting in Odoo 17, the /jsonrpc endpoint requires a specific API Key. The server detects the version and selects the correct transport transparently.
Optional schema cache. Repeated calls to odoo_fields_get are served from memory (configurable TTL cache), reducing latency in intensive work sessions.
Built-in observability (optional). Each RPC call produces an OpenTelemetry span with odoo.model, odoo.method and odoo.alias attributes. If no OTLP endpoint is configured, the server starts normally without emitting traces: graceful degradation, zero errors.
Available tools
The server exposes 18 tools organized by operation domain:
| Category | Tool | What it does |
|---|---|---|
| Read | odoo_search_read | Search and return records with ORM filters |
| Read | odoo_fields_get | Describe a model's fields (with optional cache) |
| Read | odoo_search_count | Count records without fetching data |
| Export | odoo_export_records_json | Export records via ORM respecting permissions |
| Export | odoo_export_records_csv | Same in CSV format |
| Write | odoo_create / odoo_write | Create or update records |
| Write | odoo_unlink | Delete records |
| Write | odoo_execute | Call any model method |
| Chatter | odoo_message_post | Post a message in a record's chatter |
| Metadata | odoo_version | Return the instance version and edition |
| Metadata | odoo_list_models | List installed models |
| Session | user_connection_activate | Activate the connection at session start |
The full 18-tool list covers read, write, export and introspection use cases. The table shows the most commonly used; the complete reference is in the repository.
Installing as a Claude Code plugin
The plugin ships with plugin.json for installation via uvx and a marketplace.json for self-hosting. Once installed, the odoo-setup-mcp skill walks through the initial configuration: instance URL, credentials and automatic version detection.
The plugin also includes:
- Skills:
odoo-setup-mcp,odoo-setup-cli,odoo-connect,odoo-crossversion. - Specialized agents:
odoo(general operations) andodoo-migrator(version migration tasks). - CLI fallback: TypeScript implementation over XML-RPC, for environments where the MCP server is not available.
Marketplace note: this plugin is distributed as a self-hosted installation. It is not yet published in Anthropic's official marketplace: it is an open-source plugin from Transgenia's own repository. The process of publishing in the official marketplace is under evaluation.
What is intentionally excluded from the public layer
The public version contains the generic core. What we deliberately left out:
- MX fiscal layer (CFDI/SAT): UUID validation against the Mexican SAT, CFDI vault reads,
l10n_mx_edi_cfdi_sat_statequeries. Available in supervised implementations. - VoBo middleware (Visto Bueno, approval gating): write governance that requires explicit human authorization before creating or modifying production records. Configurable enforcement option.
- S3 backup tools: instance backup and restore.
- Vision and invoice parsing tools: document and PDF reading with language vision.
These layers make sense only in the context of a supervised implementation. The public core is genuinely useful on its own: they are not "cut" features to sell upgrades, but capabilities that require an onboarding process with the team.
For more context on the base API Key layer before the plugin, Connect Odoo to Claude with an API Key and Build Views Without Python covers the baseline options and their real limitations.
Why open source and why MIT
There is a pragmatic argument: a closed MCP server creates vendor dependency. If the pricing changes, the business model shifts, or the company disappears, the AI agent stops working. With open source (MIT), the company owns the code, can self-host it, and can hire any provider to maintain it. The plugin keeps working even if Transgenia does not exist tomorrow.
There is also an ecosystem argument: the more companies contribute to an Odoo MCP server, the more robust it becomes for everyone. The compatibility layer covers Odoo 10-19 today; the community can extend it to future versions without waiting for any specific vendor to do it.
We chose MIT over AGPL so companies can integrate the plugin into their proprietary stacks without copyleft restrictions. Copyleft has its place; here we prioritized adoption.
Verified technical quality
The plugin ships with complete CI:
- 27 unit tests passing: coverage of the version compatibility table, transport fallback regression tests and cache tests.
- Linting: ruff clean on Python 3.11 and 3.12.
- TypeScript CLI: builds without errors.
- Real MCP handshake (stdio): correctly lists all 18 tools.
- Live version matrix (opt-in): against ephemeral Odoo 16, 17 and 18 instances.
How to get started
If you have Odoo and want to explore AI agent integration, the recommended path has three steps:
- Instance diagnostic: version, edition, installed modules and flows that are candidates for AI automation.
- Read-only pilot: connect the agent in read mode to validate that responses are correct before touching production data.
- Governance before writes: the VoBo middleware exists as an optional layer: enabling it is a configuration change, not a rewrite.
If you want to see the stack in real operation before deciding, our sector-specific demo shows agents working on clinic and wholesale distributor data using the same MCP protocol.
Frequently asked questions
Is MCP-Odoo-Tools free?
Yes. The public layer is MIT-licensed and has no cost. You can install and configure it yourself from the GitHub repository. The MX fiscal layer (CFDI/SAT), write governance middleware (VoBo) and other advanced components are available in Transgenia's supervised implementation packages.
Which Odoo versions are supported?
Odoo Community, Enterprise and online (SaaS) from version 10 through 19. The compatibility layer automatically resolves differences in model and field names across versions, including renames like account.invoice → account.move in v13 and other changes in later versions.
Does it work only with Claude or with other AI agents?
With any agent that implements the Model Context Protocol (MCP), the open specification published by Anthropic. Claude Code is the reference environment for which the plugin is packaged, but the server exposes a standard interface compatible with other MCP clients.
Does the plugin send my company's data to Transgenia's servers?
No. The MCP server runs in your infrastructure (or your chosen provider's) and communicates directly with your Odoo instance. Data does not pass through any Transgenia server. The plugin is simply code you run: what you do with it stays within your perimeter.
Is it approved by Anthropic as an official plugin?
Not yet. The plugin is open source and distributed from Transgenia's own repository. Transgenia is a registered partner in Anthropic's Claude Partner Network, which means Anthropic recognizes us as a partner, not that the plugin is certified or audited by them. The distinction matters: the code is open and auditable by anyone.
About the author and Transgenia
Efraín Carreón Ortiz is CEO of Centrum Transgenia, a Mexican technology boutique. He holds the official Claude Code badge (Claude Partner Badge) issued by Anthropic, verifiable on Credly.
Transgenia is an OpenAI Select Partner within the OpenAI Partner Network and a registered partner in Anthropic's Claude Partner Network. We operate twelve governed AI agents in our own production environment and accompany verifiable implementations in the healthcare and B2B sectors.
Let's talk: LinkedIn, 15-minute agenda or our contact page.
Keep reading
- Connect Odoo to Claude with an API Key and Build Views Without Python: the base layer before the plugin, to understand the baseline options and their real limitations.
- How Transgenia Runs with Governed AI Agents: the governance model (draft-first, human VoBo, MCP) surrounding this plugin in production.
- Implementing Claude in Your Business: a Phase-by-Phase Guide: the full adoption method from a registered Anthropic partner.
- MCP-Odoo-Tools user manual: the full plugin reference: installation, the 18 tools and cross-version compatibility.
- Our governed AI solutions.