Skip to content
Back to search

mcp-odoo

Odoo MCP for AI agents — gated writes, multi-instance. Hosted product: https://erpipe.com

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/erpipe-org--mcp-odoo/badge.svg)](/listings/erpipe-org--mcp-odoo)

HTML

<a href="/listings/erpipe-org--mcp-odoo"><img src="/api/listings/erpipe-org--mcp-odoo/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Two paths to a working server: set it up yourself, or paste one prompt and let your coding agent do it for you.

For humans

The fastest path is the interactive wizard via `uvx`, which fetches the package on demand:

uvx odoo-mcp --setup

The wizard asks for your Odoo URL, database, and credentials, tests the connection live, writes the config file, and prints ready-to-paste snippets for Claude Code, Cursor, and Claude Desktop. Prefer a quick smoke check instead? `uvx odoo-mcp --health`.

Using Claude Desktop on macOS? It reads MCP configuration from:

~/Library/Application Support/Claude/claude_desktop_config.json

Use an absolute Python path because GUI apps may not inherit your shell `PATH`:

{
  "mcpServers": {
    "odoo": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["-m", "odoo_mcp"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_DB": "your-database",
        "ODOO_USERNAME": "your-user",
        "ODOO_PASSWORD": "your-password-or-api-key",
        "ODOO_TRANSPORT": "xmlrpc"
      }
    }
  }
}

More client configs (Windsurf, VS Code, Zed, Continue.dev, Streamable HTTP) are in [docs/client-configs.md](./docs/client-configs.md).

Other ways to install:

pip install odoo-mcp
# or: pipx install odoo-mcp

Prefer a container? See [Docker](#docker). For local development:

git clone https://github.com/erpipe-org/mcp-odoo.git
cd mcp-odoo
uv sync --extra dev

For AI agents

Paste this into Claude Code, Cursor, Codex, or any coding agent and it will install the server for you:

Install the odoo-mcp MCP server (https://github.com/erpipe-org/mcp-odoo) in this environment:

1. Ask me for my Odoo URL, database name, username, and password or API key.
   Treat them as secrets: never echo, print, or log these values.
2. Register the server as a stdio MCP server:
   - Claude Code: claude mcp add odoo --env ODOO_URL=<url> --env ODOO_DB=<db>
     --env ODOO_USERNAME=<user> --env ODOO_PASSWORD=<secret> -- uvx odoo-mcp
   - Any other client: write the equivalent config with "command": "uvx",
     "args": ["odoo-mcp"], and the same four env vars.
3. Verify the install: run `uvx odoo-mcp --health`, then call the health_check
   MCP tool and confirm the Odoo connection is reachable.
4. Leave writes disabled (do not set ODOO_MCP_ENABLE_WRITES) unless I
   explicitly ask you to enable them.

Full machine-readable instructions: https://github.com/erpipe-org/mcp-odoo/blob/main/llms-install.md

Already know your client? One-liners and config snippets:

claude mcp add odoo --env ODOO_URL=https://mycompany.odoo.com --env ODOO_DB=mycompany \
  --env ODOO_USERNAME=agent@mycompany.com --env ODOO_PASSWORD=your-api-key -- uvx odoo-mcp

- Claude Code `.mcp.json` and Codex CLI `config.toml`: [`examples/README.md`](./examples/README.md) - Cursor `.cursor/mcp.json` + agent rules: [`examples/cursor/`](./examples/cursor/) - Windsurf, VS Code, Zed, Continue.dev, Cline, Streamable HTTP, Docker: [`docs/client-configs.md`](./docs/client-configs.md) - Machine-readable install guide for agents (Cline-style): [`llms-install.md`](./llms-install.md)

Framework SDKs

Copy-paste-runnable integrations live in [`examples/`](./examples/):

| Client | Example | | --- | --- | | Cursor | [`examples/cursor/`](./examples/cursor/) — `.cursor/mcp.json` + agent rules | | Claude Code / Codex CLI | snippets in [`examples/README.md`](./examples/README.md) | | OpenAI Agents SDK | [`examples/openai-agents/`](./examples/openai-agents/) — local + hosted variants | | LangGraph | [`examples/langgraph/`](./examples/langgraph/) — `langchain-mcp-adapters` | | CrewAI | [`examples/crewai/`](./examples/crewai/) — native `mcps=[...]` agent | | n8n | [`examples/n8n/`](./examples/n8n/) — importable workflow JSON |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 633 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Odoo MCP
  2. <!-- mcp-name: io.github.erpipe-org/mcp-odoo -->
  3. ERPipe is the managed Odoo MCP gateway from the maintainer of [`erpipe-org/mcp-odoo`](https://github.com/erpipe-org/mcp-odoo), formerly [`tuanle96/mcp-odoo`](https://github.com/tuanle96/mcp-odoo); the Python project remains the self-hosted server.
  4. <p align="center">
  5. <strong>The free AI layer for Odoo — any edition, any version.</strong><br>
  6. Odoo's built-in AI is Enterprise-only. Odoo MCP gives Community and Enterprise 16+ the same power for $0 with the LLM you already use (Claude, GPT, Gemini, DeepSeek, Ollama).<br>
  7. Five-minute install. Zero Odoo-side setup. Safe writes, real diagnostics, JSON-2 ready years before the Odoo 22 XML-RPC removal.
  8. </p>
  9. <p align="center">
  10. <a href="https://pypi.org/project/odoo-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/odoo-mcp.svg"></a>
  11. <a href="https://pypi.org/project/odoo-mcp/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/odoo-mcp.svg"></a>
  12. <a href="https://pypi.org/project/odoo-mcp/"><img alt="Downloads" src="https://img.shields.io/pypi/dm/odoo-mcp.svg"></a>
  13. <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-black.svg"></a>
  14. <a href="https://github.com/erpipe-org/mcp-odoo/actions/workflows/publish.yml"><img alt="CI" src="https://github.com/erpipe-org/mcp-odoo/actions/workflows/publish.yml/badge.svg"></a>
  15. <a href="https://github.com/erpipe-org/mcp-odoo/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/erpipe-org/mcp-odoo?style=flat"></a>
  16. <a href="https://github.com/erpipe-org/mcp-odoo/network/members"><img alt="Forks" src="https://img.shields.io/github/forks/erpipe-org/mcp-odoo?style=flat"></a>
  17. <a href="https://skills.sh/erpipe-org/mcp-odoo"><img alt="Agent Skills" src="https://skills.sh/b/erpipe-org/mcp-odoo"></a>
  18. </p>
  19. <p align="center">
  20. <a href="https://erpipe.com/"><strong>🚀 ERPipe hosted</strong> — free v1 · live at erpipe.com</a>
  21. &nbsp;·&nbsp;
  22. <a href="https://github.com/erpipe-org/erpipe"><strong>TypeScript open core</strong></a>
  23. &nbsp;·&nbsp;
  24. <a href="https://erpipe-org.github.io/mcp-odoo/services.html"><strong>🔍 Fixed-price audits</strong></a>
  25. </p>
  26. > **Want ChatGPT / Claude on a stable remote URL without running a process?**
  27. > **[ERPipe](https://erpipe.com/)** is the hosted product from the same author — free v1 public beta, live in production.
  28. > Sign up → add HTTPS Odoo instance(s) → connect once to `https://mcp.erpipe.com/mcp` (workspace OAuth, multi-instance, gated writes, audit dashboard).
  29. > This repo stays the **local / self-host Python server** (full 41-tool surface, stdio, Docker). TypeScript building blocks: [`erpipe`](https://github.com/erpipe-org/erpipe).
  30. | | **This repo (`odoo-mcp`)** | **[ERPipe hosted](https://erpipe.com/)** |
  31. |--|--|--|
  32. | Run where | Your laptop / Docker / CI | Cloudflare (managed) |
  33. | Install | `uvx odoo-mcp --setup` | Sign up at [erpipe.com](https://erpipe.com/) |
  34. | MCP URL | stdio or local HTTP | `https://mcp.erpipe.com/mcp` |
  35. | Clients | Claude Code, Cursor, local agents | **ChatGPT** (primary), Claude, Cursor, any remote MCP client |
  36. | Tool surface | **41 tools** + 11 prompts (full local pack) | **43 tools** + 7 prompts (workspace multi-instance + governance; [catalog](https://erpipe.com/tools)) |
  37. | Multi-instance | Config file / env on your machine | Dashboard + explicit `instance` key per tool |
  38. | Writes | Env gate + approval tokens (+ optional MCP elicitation) | Default OFF · HITL inbox · journal · field policy |
  39. | Audit | Optional JSONL file | Dashboard + D1 audit trail |
  40. | Cost | Free forever (MIT) | Free v1 beta (fair-use caps) |
  41. Odoo MCP turns any Odoo 16+ database into a Model Context Protocol server — using only your existing credentials. **No App Store module, no permission setup, no admin access required.** Built for local agents, IDEs, and automation tools that need real Odoo context without hand-rolled scripts or unsafe direct write access.
  42. It speaks XML-RPC for Odoo 16-18 and External JSON-2 for Odoo 19+. It exposes a compact MCP surface with read tools, diagnostics, schema discovery, migration helpers, local addon scanning, and a gated write workflow. One server can serve [multiple named Odoo instances](#multiple-odoo-instances) at once.
  43. ## Try it in 30 seconds
  44. Once configured (see [Setup](#setup)), ask your agent things like:
  45. > "Show me all customers from Spain with unpaid invoices."
  46. >
  47. > "Find products with stock below 10 units in the main warehouse."
  48. >
  49. > "Audit the `custom_billing` addon for upgrade risks before we move to Odoo 19."
  50. ## Highlights
  51. | Capability | What it gives you |
  52. | --- | --- |
  53. | 41 MCP tools | Read records and attachments, aggregate server-side, post chatter, inspect schema, build domains, scan addons, diagnose calls and upgrade logs, check data quality, access rules, resolve model renames, validate writes, and fan out across instances. |
  54. | Field-level ACL | Opt-in per-instance, per-model field allow/deny enforced on every read path (records, aggregates, knowledge index, resources). First open-source Odoo MCP with it. See [docs/field-acl.md](docs/field-acl.md). |
  55. | Cross-instance queries | Read-only fan-out across many client DBs with merged, attributed, partial-failure-tolerant results — no warehouse, no sync. See [docs/partner-playbook.md](docs/partner-playbook.md). |
  56. | Workflow prompts | 11 prompts including 6 end-to-end business workflows (invoice approval, PO match, onboarding, expense review, month-end close, pre-migration data quality) that route writes through the gate. |
  57. | Background tasks | `submit_async_task` runs long read operations (addon scans, knowledge indexing, AR/AP aging) on a bounded worker pool; poll with `get_async_task` while the agent keeps reasoning. |
  58. | Local-first knowledge search | `index_knowledge` + `search_knowledge` give BM25 relevance ranking over a bounded record slice — accent-insensitive, in-process, no embeddings service, no data leaving the machine. |
  59. | Accounting pack | `receivable_payable_aging` and `accounting_health_summary` answer the most common finance questions in one call instead of hand-built domains. |
  60. | Agent Skills pack | 4 business-workflow skills (data-quality gate, migration copilot, month-end close, agency fleet review) — `npx skills add erpipe-org/mcp-odoo`. Developing on Odoo with shell access? Add the 21-skill companion dev suite [odoo-ai-skills](https://github.com/tuanle96/odoo-ai-skills). See [skills/](./skills/). |
  61. | Tool plugins | Ship your own tools as pip packages (`odoo_mcp.tools` entry points) — opt-in via `ODOO_MCP_PLUGINS`, fail-isolated, no fork needed. Trim the surface per deployment with `ODOO_MCP_TOOLS_INCLUDE/EXCLUDE`. See [docs/plugins.md](docs/plugins.md). |
  62. | Rate limiting | Opt-in sliding-window budget per instance and tool (`ODOO_MCP_RATE_LIMIT_MODE=warn\|block`), surfaced in `health_check`. |
  63. | Multi-instance | One server, several named Odoo instances — optional `instance` parameter on every tool, `list_instances` discovery, instance-bound approval tokens, per-instance schema caches. |
  64. | 5 agent prompts | Reusable workflows for failed calls, fit/gap workshops, JSON-2 migration, safe writes, and module audits. |
  65. | Odoo 16-19 coverage | XML-RPC by default, JSON-2 opt-in for Odoo 19. |
  66. | MCP 2026-07-28 | Stateless modern protocol with `server/discover`, plus automatic compatibility with legacy `2025-11-25` clients on the same endpoint. |
  67. | Streamable HTTP | Local HTTP/SSE support for clients that do not use stdio. |
  68. | Smart field selection | `search_records` and `read_record` curate business-relevant fields when no `fields` argument is supplied — drops audit, message, binary, and unstored compute noise. Pass `fields=["*"]` to opt out. |
  69. | Server-side aggregation | `aggregate_records` pushes groupby/sum/count/avg into Postgres via `formatted_read_group` (Odoo 19+) or `read_group` (16-18). |
  70. | Chatter integration | `chatter_post` adds messages to any `mail.thread` record under the same approval-token gate as writes — or directly via `MCP_CHATTER_DIRECT=1`. |
  71. | Locale plumbing | `ODOO_LOCALE` injects `context.lang` automatically on every Odoo call (caller can override). |
  72. | Structured logging | JSON formatter and rotating file handler via `ODOO_MCP_LOG_LEVEL`, `ODOO_MCP_LOG_JSON`, `ODOO_MCP_LOG_FILE`. |
  73. | Safe writes | Direct `create`, `write`, and `unlink` are blocked; approved writes require live metadata, a same-session token, explicit confirmation, and an env gate. |
  74. | Human-in-the-loop approval | `ODOO_MCP_ELICIT_WRITES=1` shows a native MCP confirmation form (with a diff summary) before any approved write executes — token flow stays as fallback. |
  75. | Audit trail | `ODOO_MCP_AUDIT_LOG` appends one JSONL line per write-path event (preview, validate, execute, chatter) with instance and token digest. |
  76. | Resilience | Read-only calls retry connection errors with exponential backoff; schema caches are TTL- and LRU-bounded; `health_check` flags N+1 read loops. |
  77. | Real smoke tests | Docker Compose validation boots disposable Odoo 16.0, 17.0, 18.0, and 19.0 stacks, including restricted users, custom record rules, and packaged addon XML install/update. |
  78. ## Why Odoo MCP
  79. | Trait | Odoo MCP | Other MCP-Odoo bridges |
  80. | --- | --- | --- |
  81. | Setup steps on Odoo side | **0** — works with any Odoo 16+ instance using credentials you already have. | Often require installing an App Store module, configuring enabled models, and granting per-tool permissions. |
  82. | Safe write workflow | Approval token + live `fields_get` validation + explicit confirm + env gate. | Often expose direct `create`/`write`/`unlink` or a "yolo" bypass. |
  83. | Diagnostics | `diagnose_odoo_call`, `diagnose_access`, `inspect_model_relationships`, `upgrade_risk_report`, `fit_gap_report`, `business_pack_report`, `scan_addons_source`. | Usually CRUD only. |
  84. | Transport | XML-RPC (16+) **and** External JSON-2 (Odoo 19+). Ready for the Odoo 22 XML-RPC removal years early. | Usually XML-RPC only — deprecated since Odoo 19, removed in Odoo 22. |
  85. | Migration helpers | `generate_json2_payload` previews the JSON-2 body for any XML-RPC call before you migrate. | None. |
  86. | Multi-instance | Named instances in one config file, per-tool routing, tokens and caches isolated per instance. | Usually one global connection per server process. |
  87. | Agent prompts | 5 ready-made prompts for diagnose / fit-gap / JSON-2 migration / safe-write / module-audit. | Usually none. |
  88. | HTTP transport security | DNS-rebinding protection, host/origin allowlists, local-bind by default. | Often missing. |
  89. | Real Odoo smoke tests | Docker Compose harness boots disposable Odoo 16/17/18/19 stacks per release. | Often mock-based only. |
  90. | Framework examples | Copy-paste adapters for Cursor, Claude Code, OpenAI Agents, LangGraph, CrewAI, and n8n in [`examples/`](./examples/). | None. |
  91. | Audit & approval UX | JSONL audit trail + native elicitation confirm forms — without installing anything in Odoo. | Audit features usually require an Odoo-side module. |
  92. Comparing specific projects? See the per-project breakdown in [docs/comparison.md](./docs/comparison.md).
  93. ## Setup
  94. Two paths to a working server: set it up yourself, or paste one prompt and let your coding agent do it for you.
  95. ### For humans
  96. The fastest path is the interactive wizard via `uvx`, which fetches the package on demand:
  97. ```bash
  98. uvx odoo-mcp --setup
  99. ```
  100. The wizard asks for your Odoo URL, database, and credentials, tests the connection live, writes the config file, and prints ready-to-paste snippets for Claude Code, Cursor, and Claude Desktop. Prefer a quick smoke check instead? `uvx odoo-mcp --health`.
  101. Using Claude Desktop on macOS? It reads MCP configuration from:
  102. ```text
  103. ~/Library/Application Support/Claude/claude_desktop_config.json
  104. ```
  105. Use an absolute Python path because GUI apps may not inherit your shell `PATH`:
  106. ```json
  107. {
  108. "mcpServers": {
  109. "odoo": {
  110. "command": "/opt/homebrew/bin/python3",
  111. "args": ["-m", "odoo_mcp"],
  112. "env": {
  113. "ODOO_URL": "https://your-odoo-instance.com",
  114. "ODOO_DB": "your-database",
  115. "ODOO_USERNAME": "your-user",
  116. "ODOO_PASSWORD": "your-password-or-api-key",
  117. "ODOO_TRANSPORT": "xmlrpc"
  118. }
  119. }
  120. }
  121. }
  122. ```
  123. More client configs (Windsurf, VS Code, Zed, Continue.dev, Streamable HTTP) are in [docs/client-configs.md](./docs/client-configs.md).
  124. Other ways to install:
  125. ```bash
  126. pip install odoo-mcp
  127. # or: pipx install odoo-mcp
  128. ```
  129. Prefer a container? See [Docker](#docker). For local development:
  130. ```bash
  131. git clone https://github.com/erpipe-org/mcp-odoo.git
  132. cd mcp-odoo
  133. uv sync --extra dev
  134. ```
  135. ### For AI agents
  136. Paste this into Claude Code, Cursor, Codex, or any coding agent and it will install the server for you:
  137. ```text
  138. Install the odoo-mcp MCP server (https://github.com/erpipe-org/mcp-odoo) in this environment:
  139. 1. Ask me for my Odoo URL, database name, username, and password or API key.
  140. Treat them as secrets: never echo, print, or log these values.
  141. 2. Register the server as a stdio MCP server:
  142. - Claude Code: claude mcp add odoo --env ODOO_URL=<url> --env ODOO_DB=<db>
  143. --env ODOO_USERNAME=<user> --env ODOO_PASSWORD=<secret> -- uvx odoo-mcp
  144. - Any other client: write the equivalent config with "command": "uvx",
  145. "args": ["odoo-mcp"], and the same four env vars.
  146. 3. Verify the install: run `uvx odoo-mcp --health`, then call the health_check
  147. MCP tool and confirm the Odoo connection is reachable.
  148. 4. Leave writes disabled (do not set ODOO_MCP_ENABLE_WRITES) unless I
  149. explicitly ask you to enable them.
  150. Full machine-readable instructions: https://github.com/erpipe-org/mcp-odoo/blob/main/llms-install.md
  151. ```
  152. Already know your client? One-liners and config snippets:
  153. ```bash
  154. claude mcp add odoo --env ODOO_URL=https://mycompany.odoo.com --env ODOO_DB=mycompany \
  155. --env ODOO_USERNAME=agent@mycompany.com --env ODOO_PASSWORD=your-api-key -- uvx odoo-mcp
  156. ```
  157. - Claude Code `.mcp.json` and Codex CLI `config.toml`: [`examples/README.md`](./examples/README.md)
  158. - Cursor `.cursor/mcp.json` + agent rules: [`examples/cursor/`](./examples/cursor/)
  159. - Windsurf, VS Code, Zed, Continue.dev, Cline, Streamable HTTP, Docker: [`docs/client-configs.md`](./docs/client-configs.md)
  160. - Machine-readable install guide for agents (Cline-style): [`llms-install.md`](./llms-install.md)
  161. #### Framework SDKs
  162. Copy-paste-runnable integrations live in [`examples/`](./examples/):
  163. | Client | Example |
  164. | --- | --- |
  165. | Cursor | [`examples/cursor/`](./examples/cursor/) — `.cursor/mcp.json` + agent rules |
  166. | Claude Code / Codex CLI | snippets in [`examples/README.md`](./examples/README.md) |
  167. | OpenAI Agents SDK | [`examples/openai-agents/`](./examples/openai-agents/) — local + hosted variants |
  168. | LangGraph | [`examples/langgraph/`](./examples/langgraph/) — `langchain-mcp-adapters` |
  169. | CrewAI | [`examples/crewai/`](./examples/crewai/) — native `mcps=[...]` agent |
  170. | n8n | [`examples/n8n/`](./examples/n8n/) — importable workflow JSON |
  171. ## Configuration reference
  172. Set connection values in the environment:
  173. ```bash
  174. export ODOO_URL="https://your-odoo-instance.com"
  175. export ODOO_DB="your-database"
  176. export ODOO_USERNAME="your-user"
  177. export ODOO_PASSWORD="your-password-or-api-key"
  178. export ODOO_TRANSPORT="xmlrpc"
  179. ```
  180. For Odoo 19 JSON-2:
  181. ```bash
  182. export ODOO_TRANSPORT="json2"
  183. export ODOO_API_KEY="your-odoo-api-key"
  184. export ODOO_JSON2_DATABASE_HEADER="1"
  185. ```
  186. `ODOO_JSON2_DATABASE_HEADER=1` sends `X-Odoo-Database` on JSON-2 calls. Set it to `0` only when host or dbfilter routing already selects the intended database.
  187. Optional environment variables:
  188. | Variable | Default | Effect |
  189. | --- | --- | --- |
  190. | `ODOO_CONFIG_FILE` | unset | Explicit path to a config file, checked before the standard locations. |
  191. | `ODOO_LOCALE` | unset | Inject `context.lang` on every Odoo call. Caller-supplied `context.lang` always wins. |
  192. | `ODOO_MCP_MAX_SMART_FIELDS` | `15` | Cap for smart-field selection when caller omits `fields`. |
  193. | `ODOO_MCP_LOG_LEVEL` | `INFO` | Process logger level (DEBUG/INFO/WARNING/ERROR/CRITICAL). |
  194. | `ODOO_MCP_LOG_JSON` | `0` | Truthy → emit JSON-formatted log lines. |
  195. | `ODOO_MCP_LOG_FILE` | unset | Path → enable rotating file handler (10MB × 3 backups). |
  196. | `ODOO_MCP_ENABLE_WRITES` | `0` | Required for `execute_approved_write`. |
  197. | `ODOO_MCP_ALLOWED_SIDE_EFFECT_METHODS` | empty | Exact `model.method` allowlist (e.g. `sale.order.action_confirm`). |
  198. | `ODOO_MCP_POLICY_FILE` | `./odoo_mcp_policy.json` if present | Version-controllable side-effect allowlist with review metadata (see `odoo_mcp_policy.json.example`); merged with the env allowlist. |
  199. | `ODOO_MCP_ALLOW_UNKNOWN_METHODS` | `0` | Broad mode for `execute_method`. Prefer the exact allowlist above. |
  200. | `ODOO_MCP_AUDIT_LOG` | unset | Path → append one JSONL line per write-path event (preview/validate/execute/chatter), tokens stored as digests. |
  201. | `ODOO_MCP_ELICIT_WRITES` | `0` | Truthy → `execute_approved_write` asks the human via MCP elicitation (native confirm form with a diff summary) before executing; falls back to the token flow when the client cannot elicit. |
  202. | `ODOO_MCP_RETRY_ATTEMPTS` | `2` | Extra attempts for read-only calls on connection errors (0–5). Writes never retry. |
  203. | `ODOO_MCP_RETRY_BACKOFF` | `0.5` | Base retry backoff seconds; doubles per retry. |
  204. | `ODOO_MCP_SCHEMA_CACHE_TTL` | `600` | Schema cache entry lifetime in seconds. |
  205. | `ODOO_MCP_SCHEMA_CACHE_MAX` | `256` | Max schema cache entries (LRU eviction). |
  206. | `ODOO_MCP_RATE_LIMIT_MODE` | `off` | `warn` tracks per-`instance:tool` call rates in `health_check`; `block` refuses over-budget calls on the hot read tools and `execute_method`. |
  207. | `ODOO_MCP_RATE_LIMIT_WINDOW` | `60` | Sliding window length in seconds for rate tracking. |
  208. | `ODOO_MCP_RATE_LIMIT_MAX_CALLS` | `120` | Calls allowed per window per `instance:tool`. |
  209. | `ODOO_MCP_ASYNC_MAX_WORKERS` | `2` | Worker threads for `submit_async_task`. |
  210. | `ODOO_MCP_ASYNC_MAX_TASKS` | `50` | Max retained background tasks (finished tasks evicted oldest-first). |
  211. | `ODOO_MCP_ASYNC_RESULT_TTL` | `3600` | Seconds a finished background task result stays pollable. |
  212. | `ODOO_MCP_KNOWLEDGE_MAX_DOCS` | `5000` | Total documents allowed across all local BM25 knowledge indexes. |
  213. | `ODOO_MCP_FIELD_POLICY_FILE` | shared policy file | Field ACL policy (a `field_acl` key in the policy file, or a dedicated file here). Denied fields are removed from every read path. See [docs/field-acl.md](docs/field-acl.md). |
  214. | `ODOO_MCP_CROSS_INSTANCE_WORKERS` | `4` | Bounded concurrency for cross-instance fan-out tools. |
  215. | `MCP_CHATTER_DIRECT` | `0` | Truthy → `chatter_post` skips the approval token gate and posts immediately. |
  216. | `MCP_ALLOW_REMOTE_HTTP` | `0` | Truthy → permit non-local HTTP binds (still requires external auth/TLS). |
  217. | `MCP_ALLOWED_HOSTS` / `MCP_ALLOWED_ORIGINS` | local | CSV allowlists for HTTP transports. |
  218. | `ODOO_MCP_MAX_ATTACHMENT_BYTES` | `1048576` | Download cap for `read_attachment` content (hard cap 16 MiB). |
  219. | `ODOO_MCP_ATTACHMENT_UPLOAD_ROOTS` | unset | Colon-separated local directories `validate_write` may read `<field>_from_path` uploads from (mirrors `ODOO_ADDONS_PATHS`). Required — fails closed with no roots configured. |
  220. | `ODOO_MCP_MAX_ATTACHMENT_UPLOAD_BYTES` | `10485760` | Size cap for `<field>_from_path` local-file uploads (hard cap 16 MiB). |
  221. | `ODOO_MCP_AUTH_ISSUER_URL` | unset | OAuth 2.1: authorization server issuer. With the two vars below, the HTTP transport becomes a protected resource server (RFC 9728 metadata + bearer validation). |
  222. | `ODOO_MCP_AUTH_INTROSPECTION_URL` | unset | RFC 7662 token introspection endpoint of the authorization server. |
  223. | `ODOO_MCP_AUTH_RESOURCE_URL` | unset | Canonical URL of this MCP server (RFC 8707 audience check when the AS binds tokens). |
  224. | `ODOO_MCP_AUTH_REQUIRED_SCOPES` | empty | CSV scopes required on every request. |
  225. | `ODOO_MCP_AUTH_CLIENT_ID` / `_CLIENT_SECRET` | unset | Credentials for the introspection call when the AS requires client auth. |
  226. | `ODOO_MCP_AUTH_REQUIRE_AUD` | `0` | Truthy → reject tokens whose introspection response has no `aud` claim (default only checks `aud` when present). |
  227. | `ODOO_MCP_AUTH_REQUIRE_ISS` | `0` | Truthy → reject introspection responses without an `iss` claim. A present `iss` must always match `ODOO_MCP_AUTH_ISSUER_URL` (mix-up attack hardening). |
  228. | `ODOO_MCP_AUTH_CACHE_TTL` | `60` | Seconds to cache introspection verdicts (`0` disables). Bounds both AS load and revocation lag. |
  229. | `ODOO_MCP_PLUGINS` | unset | CSV entry-point names to load as third-party tool plugins (group `odoo_mcp.tools`). Installation alone activates nothing; failures are isolated and reported in `health_check`. See [docs/plugins.md](docs/plugins.md). |
  230. | `ODOO_MCP_TOOLS_INCLUDE` / `_EXCLUDE` | unset | CSV fnmatch globs trimming the registered tool surface per deployment (small agents drown in 41 tools). Removed names listed in `health_check`. |
  231. | `ODOO_MCP_INSTRUCTIONS_FILE` | unset | Plain-text file appended to the server-level MCP `instructions` every client receives — deployment-specific guidance (fiscal-year rules, naming conventions) without touching tool descriptions. |
  232. You can also use `odoo_config.json`:
  233. ```json
  234. {
  235. "url": "https://your-odoo-instance.com",
  236. "db": "your-database",
  237. "username": "your-user",
  238. "password": "your-password-or-api-key"
  239. }
  240. ```
  241. ### Multiple Odoo instances
  242. One server can talk to several Odoo databases. Add an `instances` map to your config file (auto-detected — a file without `instances` keeps the flat single-instance shape above):
  243. ```json
  244. {
  245. "default": "acme",
  246. "instances": {
  247. "acme": {
  248. "url": "https://acme.odoo.com",
  249. "db": "acme",
  250. "username": "bot",
  251. "api_key": "...",
  252. "transport": "json2"
  253. },
  254. "globex": {
  255. "url": "https://globex.odoo.com",
  256. "db": "globex",
  257. "username": "bot",
  258. "password": "...",
  259. "lang": "fr_FR",
  260. "timeout": 60
  261. }
  262. }
  263. }
  264. ```
  265. - Every read/write tool accepts an optional `instance` parameter; omitted → the `default` instance. `default` itself is optional when only one instance is defined.
  266. - Each entry supports the same keys as the flat config (`url`, `db`, `username`, `password`, `api_key`, `transport`, `json2_database_header`, `lang`) plus `timeout` and `verify_ssl`. Instance entries are self-contained: credentials and transport never fall back to env vars (so one instance can never inherit another deployment's `ODOO_API_KEY`). Only non-credential knobs (`ODOO_TIMEOUT`, `ODOO_VERIFY_SSL`, `ODOO_LOCALE`) act as fallback defaults for entries that omit them. Env overrides like `ODOO_TRANSPORT`/`ODOO_API_KEY` still apply to legacy flat configs, as before.
  267. - `ODOO_CONFIG_FILE=/path/to/config.json` points at an explicit config file, checked before `./odoo_config.json`, `~/.config/odoo/config.json`, and `~/.odoo_config.json`.
  268. - **Precedence**: when `ODOO_URL`/`ODOO_DB`/`ODOO_USERNAME`/`ODOO_PASSWORD` are all set, the environment wins and defines a single instance named `default` — unset them to use a multi-instance file.
  269. - Instance names must match `[A-Za-z0-9_-]{1,64}`. Clients connect lazily — an instance is only contacted when a tool targets it.
  270. - Discovery: the `list_instances` tool returns configured names, URLs, databases, and transports — never credentials.
  271. - Write-approval tokens encode the instance name, so a token validated against one instance can never execute on another.
  272. - MCP resources (`odoo://…`) always use the default instance in this release; use tools for multi-instance access.
  273. ## Run
  274. Start the MCP server over stdio:
  275. ```bash
  276. odoo-mcp
  277. ```
  278. or:
  279. ```bash
  280. python -m odoo_mcp
  281. ```
  282. Start Streamable HTTP for local clients:
  283. ```bash
  284. odoo-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp
  285. ```
  286. Non-local HTTP binds are rejected unless you pass `--allow-remote-http` or set `MCP_ALLOW_REMOTE_HTTP=1`. This server does not include built-in HTTP authentication. Put remote HTTP deployments behind your own authentication, TLS, and network policy.
  287. Check runtime posture without starting the server loop:
  288. ```bash
  289. odoo-mcp --health
  290. ```
  291. ## MCP Tools
  292. 41 tools grouped by use case. Each tool name is a single-purpose handle the agent can call. Tools that talk to Odoo accept an optional `instance` parameter when multiple instances are configured (see [Multiple Odoo instances](#multiple-odoo-instances)).
  293. ### Read & Discover (11)
  294. | Tool | Purpose |
  295. | --- | --- |
  296. | `list_models` | List Odoo model technical names and labels. |
  297. | `get_model_fields` | Read field metadata for one model. |
  298. | `search_records` | Run bounded read-only `search_read`. Smart-field selection when caller omits `fields`. |
  299. | `read_record` | Read one record by model and ID. Smart-field selection when caller omits `fields`. |
  300. | `aggregate_records` | Server-side groupby/aggregation via `formatted_read_group` (Odoo 19+) or `read_group` (16-18). |
  301. | `search_employee` | Search employees by name. |
  302. | `search_holidays` | Search leave records by date range. |
  303. | `get_odoo_profile` | Read server version, user context, transport, database, and installed module summary. |
  304. | `schema_catalog` | Build a bounded model catalog with optional field metadata. |
  305. | `build_domain` | Build and validate an Odoo domain from structured conditions. |
  306. | `read_attachment` | Read an `ir.attachment`'s metadata and size-capped base64 content (`ODOO_MCP_MAX_ATTACHMENT_BYTES`, default 1 MiB). |
  307. ### Write & Operate (5)
  308. | Tool | Purpose |
  309. | --- | --- |
  310. | `preview_write` | Produce a non-executing approval payload for `create`, `write`, or `unlink`. |
  311. | `validate_write` | Validate a write payload against trusted live `fields_get` metadata. |
  312. | `execute_approved_write` | Execute only a same-session, live-validated, confirmed write when `ODOO_MCP_ENABLE_WRITES=1`. |
  313. | `execute_method` | Execute a reviewed model method. Direct `create`, `write`, and `unlink` are blocked. Side-effect methods require an exact allowlist or `ODOO_MCP_ALLOW_UNKNOWN_METHODS=1`. |
  314. | `chatter_post` | Post a chatter message on a `mail.thread` record. Default mode requires the approval-token preview/execute flow. |
  315. ### Diagnose (3)
  316. | Tool | Purpose |
  317. | --- | --- |
  318. | `diagnose_odoo_call` | Diagnose a model call without executing it. |
  319. | `diagnose_access` | Diagnose ACL and record-rule visibility for the current Odoo credential. |
  320. | `inspect_model_relationships` | Group relationship fields, required fields, and create/write hints. |
  321. ### Migrate (3)
  322. | Tool | Purpose |
  323. | --- | --- |
  324. | `generate_json2_payload` | Convert XML-RPC-shaped input into JSON-2 endpoint, headers, and named body. |
  325. | `upgrade_risk_report` | Surface transport, method, and migration risks across Odoo versions. |
  326. | `lookup_model_history` | Resolve outdated model names (`account.invoice` → `account.move`) against a curated per-version rename catalog. |
  327. ### Audit & Plan (3)
  328. | Tool | Purpose |
  329. | --- | --- |
  330. | `scan_addons_source` | Scan local addon source without importing addon code. |
  331. | `fit_gap_report` | Classify requirements into standard, configuration, Studio, custom module, avoid, or unknown. |
  332. | `business_pack_report` | Report expected modules, models, and discovery calls for sales, CRM, inventory, accounting, or HR. |
  333. ### Knowledge search — local-first (3)
  334. | Tool | Purpose |
  335. | --- | --- |
  336. | `index_knowledge` | Fetch a bounded record slice once and build a local BM25 index (accent-insensitive; data never leaves the machine). |
  337. | `search_knowledge` | Relevance-ranked free-text search over indexed records with zero further RPC calls. |
  338. | `knowledge_stats` | Report per-model index sizes and the `ODOO_MCP_KNOWLEDGE_MAX_DOCS` budget. |
  339. ### Accounting (2)
  340. | Tool | Purpose |
  341. | --- | --- |
  342. | `receivable_payable_aging` | Aged AR/AP report bucketed by days overdue (not due / 1-30 / 31-60 / 61-90 / 90+), with per-partner totals. |
  343. | `accounting_health_summary` | Open receivable/payable item counts plus the draft invoice backlog. |
  344. ### Background tasks (4)
  345. | Tool | Purpose |
  346. | --- | --- |
  347. | `submit_async_task` | Run an allowlisted long read operation (`scan_addons_source`, `index_knowledge`, `receivable_payable_aging`) on a bounded worker pool. Writes are never accepted. |
  348. | `get_async_task` | Poll a task's status and result. |
  349. | `cancel_async_task` | Cancel a pending or running task. |
  350. | `list_async_tasks` | List live and recently finished tasks. |
  351. ### Cross-instance fan-out — read-only (3)
  352. One question across many configured instances, merged and attributed. See the [partner playbook](docs/partner-playbook.md).
  353. | Tool | Purpose |
  354. | --- | --- |
  355. | `search_across_instances` | Search every opted-in instance (or a list/tag selection); rows tagged with `_instance`, partial results on per-instance failure. |
  356. | `aggregate_across_instances` | Group/aggregate per instance plus additive grand totals across the fleet. |
  357. | `accounting_health_across_instances` | AR/AP aging across every client DB with combined buckets — the partner-network sweep. |
  358. ### Utility (2)
  359. | Tool | Purpose |
  360. | --- | --- |
  361. | `health_check` | Report non-secret MCP runtime posture, including rate-limit counters and field-ACL status when enabled. |
  362. | `list_instances` | List configured Odoo instance names, URLs, databases, transports, and cross-instance tags — never credentials. |
  363. ## Resources
  364. | URI | Description |
  365. | --- | --- |
  366. | `odoo://models` | List available models. |
  367. | `odoo://model/{model_name}` | Read model metadata and fields. |
  368. | `odoo://record/{model_name}/{record_id}` | Read one record. |
  369. | `odoo://search/{model_name}/{domain}` | Search records with a bounded domain. |
  370. ## Prompts
  371. 11 prompts: 5 diagnostic, plus 6 operational **workflow** prompts that encode end-to-end business processes and route every write through the approval gate.
  372. | Prompt | Use it for |
  373. | --- | --- |
  374. | `diagnose_failed_odoo_call` | Root-cause a failing Odoo call before retrying. |
  375. | `fit_gap_workshop` | Turn raw requirements into Odoo fit/gap buckets. |
  376. | `json2_migration_plan` | Plan XML-RPC or JSON-RPC migration to External JSON-2. |
  377. | `safe_write_review` | Review a proposed `create`, `write`, or `unlink`. |
  378. | `custom_module_audit` | Audit local addon source with scan, risk, and business evidence. |
  379. | `invoice_approval_chain` | Triage draft invoices and post each through the write gate with human checkpoints. |
  380. | `po_to_receipt` | Three-way match a purchase order against receipt and bill; flags discrepancies (read-only). |
  381. | `customer_onboarding` | Dedup-check, then gated-create a customer with contacts and payment terms. |
  382. | `expense_claim_review` | Policy-check pending expense claims, then gated approve/refuse. |
  383. | `accounting_close_checklist` | Read-only month-end checklist: aging, unreconciled items, draft backlog. |
  384. ## Safe Write Model
  385. Writes are intentionally boring.
  386. 1. `preview_write` creates a canonical, non-executing payload.
  387. 2. `validate_write` checks model metadata, required fields, readonly fields, relation hints, record IDs, and payload shape.
  388. 3. `execute_approved_write` runs only when all gates pass:
  389. - the approval came from `validate_write` in the same server process,
  390. - validation used trusted, non-empty live Odoo `fields_get` metadata,
  391. - the token has not expired or been consumed,
  392. - `confirm=true` is passed,
  393. - `ODOO_MCP_ENABLE_WRITES=1` is set.
  394. Odoo access rules, record rules, and server-side constraints still decide the final result.
  395. Batch creates go through the same gates: pass `values_list` (one dict per
  396. record, max 100) to `preview_write`/`validate_write` — execution maps to a
  397. single atomic Odoo `create(vals_list)` call. Per-record differing `write`
  398. values are deliberately unsupported (they would need one non-atomic RPC per
  399. record). Optional extras: `ODOO_MCP_ELICIT_WRITES=1` adds a native
  400. human-confirmation form, `ODOO_MCP_AUDIT_LOG` records every write-path event.
  401. Large binary fields (a resume attached to `ir.attachment.datas`, a product
  402. image, ...) don't have to be inlined as base64 in the tool call — pass
  403. `<field>_from_path` instead (e.g. `datas_from_path: "/local/path/cv.pdf"`) to
  404. `validate_write`. The server reads the file itself; the approval only ever
  405. carries a `sha256:<hex>:<size>` fingerprint for that field, never the real
  406. content, so nothing large has to round-trip through the calling agent's
  407. context. Requires `ODOO_MCP_ATTACHMENT_UPLOAD_ROOTS` (fails closed otherwise)
  408. and respects `ODOO_MCP_MAX_ATTACHMENT_UPLOAD_BYTES`. No new tool — this rides
  409. the same `preview_write` → `validate_write` → `execute_approved_write` gate as
  410. every other write.
  411. Reviewed side-effect methods such as `sale.order.action_confirm` can be enabled
  412. one by one:
  413. ```bash
  414. export ODOO_MCP_ALLOWED_SIDE_EFFECT_METHODS="sale.order.action_confirm,res.partner.message_post"
  415. ```
  416. `ODOO_MCP_ALLOW_UNKNOWN_METHODS=1` is still supported for trusted deployments,
  417. but `health_check` reports it as broad mode. Prefer exact allowlist entries when
  418. you only need a small number of reviewed methods.
  419. ## Docker
  420. Use the prebuilt GHCR image:
  421. ```bash
  422. docker pull ghcr.io/erpipe-org/mcp-odoo:latest
  423. ```
  424. Or build it locally:
  425. ```bash
  426. docker build -t mcp/odoo:latest -f Dockerfile .
  427. ```
  428. Run over stdio from an MCP client (replace `mcp/odoo:latest` with `ghcr.io/erpipe-org/mcp-odoo:latest` to use the prebuilt image):
  429. ```json
  430. {
  431. "mcpServers": {
  432. "odoo": {
  433. "command": "docker",
  434. "args": [
  435. "run",
  436. "-i",
  437. "--rm",
  438. "-e", "ODOO_URL",
  439. "-e", "ODOO_DB",
  440. "-e", "ODOO_USERNAME",
  441. "-e", "ODOO_PASSWORD",
  442. "-e", "ODOO_TRANSPORT",
  443. "-e", "ODOO_API_KEY",
  444. "mcp/odoo:latest"
  445. ]
  446. }
  447. }
  448. }
  449. ```
  450. Run Streamable HTTP locally:
  451. ```bash
  452. docker run --rm \
  453. -p 127.0.0.1:8000:8000 \
  454. -e ODOO_URL \
  455. -e ODOO_DB \
  456. -e ODOO_USERNAME \
  457. -e ODOO_PASSWORD \
  458. -e ODOO_TRANSPORT \
  459. -e ODOO_API_KEY \
  460. mcp/odoo:latest \
  461. --transport streamable-http \
  462. --host 0.0.0.0 \
  463. --port 8000 \
  464. --allow-remote-http
  465. ```
  466. ## Test
  467. Run the normal quality gates:
  468. ```bash
  469. uv run python -m ruff check .
  470. uv run python -m mypy src
  471. uv run python -m pytest
  472. ```
  473. Run real Odoo smoke tests:
  474. ```bash
  475. uv run --python 3.12 --with-editable . scripts/odoo_compose_smoke.py \
  476. --versions 16.0 17.0 18.0 19.0 \
  477. --timeout 360 \
  478. --inspector-smoke
  479. ```
  480. The smoke harness boots disposable Docker Compose stacks, validates direct Odoo access, validates MCP stdio, and for Odoo 19 also validates JSON-2 and Streamable HTTP.
  481. Run the multi-instance smoke (one stack, three databases, two accounts on one instance):
  482. ```bash
  483. uv run --python 3.12 --with-editable . scripts/odoo_multi_instance_smoke.py
  484. ```
  485. ## Compatibility
  486. XML-RPC remains the default transport for broad compatibility. Odoo 19 supports External JSON-2 through `ODOO_TRANSPORT=json2`. XML-RPC and JSON-RPC are deprecated since Odoo 19 and scheduled for removal in Odoo 22 (fall 2028), so new integrations should plan for JSON-2.
  487. ## Documentation
  488. | Guide | Covers |
  489. | --- | --- |
  490. | [docs/comparison.md](./docs/comparison.md) | How Odoo MCP compares to other Odoo MCP bridges |
  491. | [docs/architecture.md](./docs/architecture.md) | System shape, transports, safety boundaries |
  492. | [docs/multi-instance.md](./docs/multi-instance.md) | Multi-database config, routing, isolation model |
  493. | [docs/troubleshooting.md](./docs/troubleshooting.md) | From error text to root cause (ACL, record rules, routing) |
  494. | [docs/performance.md](./docs/performance.md) | Cache/retry knobs, batching patterns, N+1 detection |
  495. | [docs/client-configs.md](./docs/client-configs.md) | Claude Desktop, Docker, Streamable HTTP setups |
  496. | [docs/testing.md](./docs/testing.md) | Local gates and the Docker Compose smoke harness |
  497. ## Contributing
  498. Issues, pull requests, and compatibility reports are welcome. Start with [CONTRIBUTING.md](./CONTRIBUTING.md), include your Odoo version, transport, client type, and the verification you ran.
  499. ## Security
  500. Do not publish logs that contain Odoo credentials, API keys, database names from private environments, or full Odoo debug traces. Report vulnerabilities through [SECURITY.md](./SECURITY.md).
  501. ## License
  502. MIT. See [LICENSE](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.