odoo-agent-mcp

A version-agnostic MCP server + code-comprehension engine that gives AI agents (Claude Code / Claude Desktop / Cursor / any MCP client) full command of any Odoo app on any Odoo version — its data, its schema, its source code, and how the two relate.

It answers, for developers and operations teams alike:

• What data is in the DB, and how do model classes map to tables and columns?
• What code is where, how does the backend work, and how do modules inherit each other?
• Show me a flowchart of the system / a user flow.
• Where would a change break things? Help me implement a feature or fix a bug.

---

Why this exists (the two-domain problem)

Almost every existing Odoo AI tool covers only Domain A — live data & metadata (reachable over Odoo's API). Very few touch Domain B — the source code (what the backend actually is). Real developer/ops command needs both, and they come from different places: Domain A from the running server, Domain B from the repository. This project fuses them.

See ARCHITECTURE.md for the full design and REUSE_MAP.md for how this relates to existing open-source Odoo MCP/LLM projects.

---

Capability tiers (graceful degradation)

The server probes each instance at connect time and advertises only the tools it can honour, so one codebase serves a locked SaaS tenant and a self-hosted repo alike.

Tier	Requires	Unlocks
TIER_0	API credentials only (works on locked Odoo Online)	Data CRUD, model/field metadata, model↔table↔column mapping, relationship graph
TIER_1	Companion module odoo_agent_bridge installed	Deep introspection endpoint, safe-method catalogue
TIER_2	Read access to the module source repo (self-hosted / Odoo.sh)	Source AST analysis, _inherit graphs, flowcharts, source↔DB drift detection, feature/bug workflows

---

Supported Odoo versions

Odoo 13 → 19+. The ORM surface (search, read, fields_get, execute_kw, ir.model*) is stable across these versions; only the wire protocol differs, and that is isolated behind a transport adapter:

Odoo version	Default transport
13 – 18	XML-RPC (fallback: JSON-RPC)
19+	JSON-2 (POST /json/2/<model>/<method>, bearer API key)

XML-RPC / JSON-RPC endpoints are deprecated in Odoo 19 and scheduled for removal (SaaS ~19.1, on-prem/Odoo.sh ~20–22). JSON-2 is implemented now so the tool outlives that removal.

---

Install

python -m venv .venv
# Windows PowerShell:  .venv\Scripts\Activate.ps1
# bash:                source .venv/bin/activate
pip install -e ".[dev]"

Configure

Copy .env.example to .env and fill in:

ODOO_URL=https://my-instance.odoo.com
ODOO_DB=my_database
ODOO_USERNAME=admin
ODOO_API_KEY=xxxxxxxx        # API key (required for JSON-2 / Odoo 19+)
# ODOO_PASSWORD=...          # legacy auth for <=18 if no API key
ODOO_SOURCE_PATH=/path/to/addons   # optional -> unlocks TIER_2 code intel

Run as an MCP server

odoo-agent-mcp                     # stdio transport (Claude Desktop / Code)

Register in an MCP client (e.g. Claude Code .mcp.json):

{
  "mcpServers": {
    "odoo": { "command": "odoo-agent-mcp" }
  }
}

---

Testing

pytest                       # unit tests — run anywhere, no Odoo needed
pytest -m e2e                # live end-to-end — REQUIRES the Docker matrix below
docker compose -f docker/docker-compose.yml up -d   # Odoo 15/17/19 + Postgres

Honest status: unit tests (mapping engine, AST engine, transport factory, tier logic) run and pass in this environment. The live e2e suite needs a running Odoo; it is written and skips automatically when no server is reachable. See tests/e2e/README.md. TODO markers flag every path that is not yet live-verified.

---

Status

v0.1.0 — foundation: transport layer, tier detection, mapping engine, code-comprehension engine, MCP wiring, companion-module skeleton, unit tests. Roadmap in ARCHITECTURE.md.