MCP-Odoo-Tools — CE, EE & online (Odoo 10-19)

Links: Homepage · Documentation · Support (dev@transgenia.org, WhatsApp +52 55 8034 0405) · Privacy policy · Terms of use · License: MIT

A Claude Code / Cowork plugin that unifies Odoo tooling into one install:

• MCP server (primary) — a clean-room, MIT-licensed Python server exposing native Odoo tools (odoo_search, odoo_read, odoo_create, odoo_write, odoo_export_records_json/csv, odoo_version, ...) over JSON-2 (Odoo's new API, saas~18.4 / 19.0+) or JSON-RPC, with automatic XML-RPC fallback, and a cross-version compatibility layer that makes a single tool call work across Community, Enterprise and online (SaaS) from Odoo 10 through 19.

• CLI fallback — a lightweight TypeScript XML-RPC CLI (Node-only) for when you can't run the MCP server, or for scripted batch access.

• Agents, skills, commands and domain context to drive both surfaces.

Built and maintained by Transgenia, a Registered partner of Anthropic. (Registered tier — this plugin is an independent open-source project, not an Anthropic-certified or first-party product.)

Why this exists

Odoo's model and field names drift across versions (account.invoice → account.move at v13, analytic fields at v16, package models near v19, the RPC API itself from v19, and more), and Enterprise adds models Community lacks. This plugin absorbs those differences behind one stable tool surface so you don't hand-branch per version.

Related MCP server: odoo-mcp-server

Where it works

The Odoo tools run as a local stdio MCP server (python3, 3.9+) on the machine where the session runs, so they need Claude Code or a local Cowork session. Surfaces that ignore local MCP servers load only the skills and commands, which cannot reach Odoo without the tools. Source: plugin component support.

Install

/plugin marketplace add Transgenia/MCP-Odoo-Tools-CE-EE-and-online
/plugin install odoo-tools
/odoo-tools:odoo-setup-mcp

/odoo-tools:odoo-setup-mcp is the guided route: it detects what is already set up and walks you through setup → verification → hands-on training → daily use → deployment to your team or production, one question at a time. No Odoo to practise with? It offers a local sandbox (below).

Claude Code prompts for the connection options when the plugin is enabled (change them later in /plugin → odoo-tools → Configure options). The API key and password are sensitive options stored in the OS secure credential store — never in settings.json or your shell profile. The setup skill then verifies the connection with odoo_version.

Requirements

• MCP server: Python 3.9+ available as python3 on PATH. The plugin runs the bundled server source directly: python3 ${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py. The server uses only the Python standard library, so nothing is installed or downloaded when it starts.

  • Linux and macOS usually already have python3 (on macOS it comes with Apple's Command Line Tools).

  • Windows: the command must be named python3. The Microsoft Store Python provides python3.exe; the python.org installer provides only python and py. Either install Python from the Microsoft Store, or put a python3.exe on PATH (e.g. a copy of or hard link to python.exe in the Python folder). A PowerShell or doskey alias is not enough: Claude Code starts the command directly, not through your shell.

• CLI fallback (optional): Node.js 18+.

What runs on your machine

• MCP server — python3 ${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py: readable Python source shipped in this plugin, with zero third-party runtime dependencies. It talks only to the Odoo URL you configure (plus your own OTLP collector, if you opt in with ODOO_OTEL_ENDPOINT).

• SessionStart hook — runs python3 --version and prints a warning only when python3 is not runnable (the MCP server could not start). It reads no plugin option or secret and contacts nothing.

• Local infrastructure (only if you run /odoo-tools:deploy-local and confirm) — Docker containers on your machine: the sandbox (PostgreSQL + Odoo on 127.0.0.1, files in ~/.odoo-tools/sandbox) or the MCP server image. Nothing starts automatically; no hook runs Docker.

• CLI fallback (only if you run /odoo-tools:odoo-setup-cli) — copies the bundled CLI source to ~/.claude/tools/odoo-cli, runs npm install and npm run build there, and creates an owner-only .env with placeholders that you fill in with your credentials yourself.

Local infrastructure: /odoo-tools:deploy-local

Provided by Transgenia, started only when you run the command (Docker required):

• Sandbox — PostgreSQL + Odoo Community 10.0 to 19.0 on your machine, bound to 127.0.0.1, with a database (demo data optional) ready for the plugin. Images come from ghcr.io/transgenia (mirrors of the official odoo and postgres images) with automatic fallback to Docker Hub. Passwords are generated locally into ~/.odoo-tools/sandbox/.env (owner-only) and never printed. Script: scripts/deploy_local.py (standard library only). status, down, logs and destroy --yes manage it afterwards. Odoo 10.0-16.0 are for testing and migrations only (Odoo S.A. maintains the three latest series); images up to 15.0 are amd64-only (ARM Linux needs binfmt/QEMU emulation). Each series gets a PostgreSQL it supports. Community (CE) only: Transgenia cannot provide Odoo Enterprise (licensed by Odoo S.A.) or Odoo Online (Odoo S.A.'s SaaS) instances — connect your own instance to use them (on Odoo Online, the plan must include external API access).

• MCP server as a container — ghcr.io/transgenia/odoo-mcp-tools, for machines without Python 3.9+, connected to an existing Odoo.

Configuration

As a plugin, configure through the plugin options above. When you run the server standalone (python3 server/run_stdio.py from a checkout, odoo-mcp after pip install ./server, or Docker), it reads these environment variables:

* one of ODOO_API_KEY or ODOO_PASSWORD.

Tools

28 MCP tools. With Read-only mode (ODOO_READONLY=1) every write tool is refused before anything reaches Odoo.

The Odoo Online tools cover what an Online database makes hard: no custom Python, API access on Custom plans only, API keys that expire (18+), a new saas~X.Y line every few months, no PDF rendering over RPC, and imports as the sanctioned bulk path.

Both import tools take at most 500 rows per call and never run by themselves: the preview does not import, and the agent asks before odoo_import. Odoo's XML-RPC cannot return the empty values an import result carries, so a session on XML-RPC refuses them instead of risking a saved import reported as an error. On Odoo Online, pace bulk work (about 1 call per second, no parallel calls).

Transports

Odoo 19 deprecates /xmlrpc and /jsonrpc (every call logs a warning on the Odoo server), and Odoo 22 and Odoo Online saas~21.1 remove them. Their replacement, JSON-2 (/json/2/<model>/<method>), exists from saas~18.4 and 19.0 and accepts an API key only.

With ODOO_TRANSPORT_PREF=auto (the default) the server reads the version first (the web client's own route: no login, nothing in the Odoo log) and then:

• on Odoo 10 to 18 (and saas~18.1-18.3) it uses JSON-RPC, then XML-RPC, as before;

• on saas~18.4 / 19.0+ with an API key it uses JSON-2, falling back to JSON-RPC and XML-RPC only when a proxy blocks JSON-2;

• with a password, or with user:pass@ in ODOO_URL (whose basic auth takes the Authorization header JSON-2 needs), it stays on the deprecated endpoints, and on 19+ odoo_version returns a transport_notice saying how to switch;

• on saas~21.1 / Odoo 22+ it needs an API key (JSON-2 is the only endpoint left).

json2 forces JSON-2; jsonrpc and xmlrpc force that endpoint. None of them switch transport by themselves. odoo_version reports the transport in use. A call moves to another transport only when that cannot run it twice, and a rate limit (HTTP 429) never switches transport: reads wait for Retry-After, writes are reported. On JSON-2, odoo_execute takes the record ids in ids and the other arguments by name in kwargs. Details: docs/compat-matrix.md.

The MCP server does not persist credentials to disk. Two caveats worth stating plainly:

• The optional CLI fallback keeps your credentials in a local .env under ~/.claude/tools/odoo-cli (owner-only; you type the secret in yourself). See SECURITY.md.

• When you drive Odoo through an AI agent, the tool results (the Odoo records you query) are returned to your MCP client and sent to your model provider (e.g. Anthropic, for Claude) to be processed, exactly like any other tool an agent uses. The MCP server talking directly to Odoo means Transgenia never proxies or stores your data; it does not mean company data is withheld from the model.

Telemetry (opt-in, disabled by default)

No usage data leaves your machine unless you opt in with ODOO_TELEMETRY=opt-in and manually share the payload shown by /odoo-doctor (which calls the read-only odoo_telemetry_preview tool). When enabled, only plugin_version, odoo_version_major, edition/deployment labels and aggregate generic tool counters are included — never URL, DB, login, secrets, PII, modules or billing. No schedules, no boot hooks, no background sends. (This covers the telemetry payload only; ODOO_METRICS/ODOO_OTEL_ENDPOINT remain separate explicit opt-ins for local Prometheus/OTLP observability.) Details: SECURITY.md.

Privacy

Privacy policy · Transgenia receives and retains no data from this plugin. It reads records (which may include personal data such as names, emails and addresses) from your own Odoo only when asked. Services it contacts:

• Your Odoo instance (the URL you configure) — from the MCP server, or from the optional CLI fallback.

• Your model provider — tool results go back to your MCP client and model, as with any tool.

• npm, only if you set up the optional CLI fallback (npm install; no Odoo data sent). The MCP server downloads nothing.

• Optional, off by default: your own OTLP collector (ODOO_OTEL_ENDPOINT).

Corporate notice: https://transgenia.org/en/legal-privacy.html.

Support matrix

Details and the delta table: docs/compat-matrix.md.

Architecture

See docs/architecture.md. In short: transport (json2/jsonrpc/xmlrpc, selected per version and credential) → session (auth + version/edition facts + schema cache) → compat (resolve model/field/capability) → tools → MCP stdio.

Scope

This is the public generic core: it talks to Odoo and nothing else. Any localization-, governance- or tenant-specific engines (e.g. country e-invoicing, approval workflows, backups, document AI) are intentionally out of scope and are not part of this repository.

Support — Transgenia

Transgenia builds and maintains this plugin and provides maintenance, support, training and assisted deployment of Claude + Odoo (hosting, migrations, integrations, customizations). Official channels only:

• Email: dev@transgenia.org

• WhatsApp: +52 55 8034 0405 — https://wa.me/525580340405

The plugin points you to these channels at the moments they matter (setup blocked, end of training, deployment); it does not add them to unrelated answers. It works with any Odoo instance, with or without a support contract. See also SUPPORT.md.

Development

cd server
python3 -m venv .venv && . .venv/bin/activate   # or: uv venv && uv pip install ...
pip install -e ".[dev,cache]"
pytest -q -m "not live"
ruff check src tests

The dev extra adds the official mcp package (Python 3.10+ only) for one interop test that drives this server with the official MCP client; the server itself never imports it, and the plugin never installs it.

License

MIT © Transgenia (Centrum Transgenia SAS). See LICENSE and NOTICE for third-party attributions.

The Terms of Use (Términos de uso, the prevailing text) complement the MIT license: trademarks, support, privacy, third-party licenses and governing law (Mexico).