Odoo MCP Server

<!-- mcp-name: io.github.tuanle96/mcp-odoo -->

<p align="center">
<strong>The free AI layer for Odoo — any edition, any version.</strong><br>
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>
Five-minute install. Zero Odoo-side setup. Safe writes, real diagnostics, JSON-2 ready years before the Odoo 22 XML-RPC removal.
</p>

<p align="center">
<a href="https://pypi.org/project/odoo-mcp/"></a>
<a href="https://pypi.org/project/odoo-mcp/"></a>
<a href="https://pypi.org/project/odoo-mcp/"></a>
<a href="./LICENSE"></a>
<a href="https://github.com/tuanle96/mcp-odoo/actions/workflows/publish.yml"></a>
<a href="https://github.com/tuanle96/mcp-odoo/stargazers"></a>
<a href="https://github.com/tuanle96/mcp-odoo/network/members"></a>
<a href="https://skills.sh/tuanle96/mcp-odoo"></a>
</p>

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.

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 at once.

Try it in 30 seconds

Once configured (see Setup), ask your agent things like:

> "Show me all customers from Spain with unpaid invoices."
>
> "Find products with stock below 10 units in the main warehouse."
>
> "Audit the custom_billing addon for upgrade risks before we move to Odoo 19."

Highlights

| Capability | What it gives you |
| --- | --- |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| Accounting pack | receivable_payable_aging and accounting_health_summary answer the most common finance questions in one call instead of hand-built domains. |
| Agent Skills pack | 4 business-workflow skills (data-quality gate, migration copilot, month-end close, agency fleet review) — npx skills add tuanle96/mcp-odoo. Developing on Odoo with shell access? Add the 21-skill companion dev suite odoo-ai-skills. See skills/. |
| 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. |
| Rate limiting | Opt-in sliding-window budget per instance and tool (ODOO_MCP_RATE_LIMIT_MODE=warn\|block), surfaced in health_check. |
| 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. |
| 5 agent prompts | Reusable workflows for failed calls, fit/gap workshops, JSON-2 migration, safe writes, and module audits. |
| Odoo 16-19 coverage | XML-RPC by default, JSON-2 opt-in for Odoo 19. |
| Streamable HTTP | Local HTTP/SSE support for clients that do not use stdio. |
| 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. |
| Server-side aggregation | aggregate_records pushes groupby/sum/count/avg into Postgres via formatted_read_group (Odoo 19+) or read_group (16-18). |
| 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. |
| Locale plumbing | ODOO_LOCALE injects context.lang automatically on every Odoo call (caller can override). |
| Structured logging | JSON formatter and rotating file handler via ODOO_MCP_LOG_LEVEL, ODOO_MCP_LOG_JSON, ODOO_MCP_LOG_FILE. |
| Safe writes | Direct create, write, and unlink are blocked; approved writes require live metadata, a same-session token, explicit confirmation, and an env gate. |
| 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. |
| Audit trail | ODOO_MCP_AUDIT_LOG appends one JSONL line per write-path event (preview, validate, execute, chatter) with instance and token digest. |
| Resilience | Read-only calls retry connection errors with exponential backoff; schema caches are TTL- and LRU-bounded; health_check flags N+1 read loops. |
| 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. |

Why Odoo MCP

| Trait | Odoo MCP | Other MCP-Odoo bridges |
| --- | --- | --- |
| 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. |
| Safe write workflow | Approval token + live fields_get validation + explicit confirm + env gate. | Often expose direct create/write/unlink or a "yolo" bypass. |
| Diagnostics | diagnose_odoo_call, diagnose_access, inspect_model_relationships, upgrade_risk_report, fit_gap_report, business_pack_report, scan_addons_source. | Usually CRUD only. |
| 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. |
| Migration helpers | generate_json2_payload previews the JSON-2 body for any XML-RPC call before you migrate. | None. |
| Multi-instance | Named instances in one config file, per-tool routing, tokens and caches isolated per instance. | Usually one global connection per server process. |
| Agent prompts | 5 ready-made prompts for diagnose / fit-gap / JSON-2 migration / safe-write / module-audit. | Usually none. |
| HTTP transport security | DNS-rebinding protection, host/origin allowlists, local-bind by default. | Often missing. |
| Real Odoo smoke tests | Docker Compose harness boots disposable Odoo 16/17/18/19 stacks per release. | Often mock-based only. |
| Framework examples | Copy-paste adapters for Cursor, Claude Code, OpenAI Agents, LangGraph, CrewAI, and n8n in examples/. | None. |
| Audit & approval UX | JSONL audit trail + native elicitation confirm forms — without installing anything in Odoo. | Audit features usually require an Odoo-side module. |

Comparing specific projects? See the per-project breakdown in docs/comparison.md.

Setup

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.

Other ways to install:

```bash
pip install odoo-mcp