odoo-mcp: a self-hosted MCP server that puts Odoo 16+ behind an AI agent

What odoo-mcp solves, and who it is written for

Odoo ships an AI layer, but the README states that Odoo's built-in AI is Enterprise-only. Anyone on Community, or on an Enterprise instance who wants a different model, has to either write XML-RPC glue by hand or hand an agent a database password and hope. odoo-mcp sits in that gap. It is a Python package that speaks the Model Context Protocol to the agent and XML-RPC or External JSON-2 to Odoo, so the agent never touches Odoo directly.

The intended user is not an Odoo developer. It is someone who already runs Claude Code, Cursor, or a local agent framework and wants that agent to answer questions about customers, stock, invoices and addons without a custom script per question. The README's own examples are business questions: customers in Spain with unpaid invoices, products below ten units in the main warehouse, an audit of a `custom_billing` addon before an Odoo 19 move.

The secondary audience is agencies and partners running many client databases. The repository ships a `docs/partner-playbook.md` and a multi-instance config example, which points at read-only fan-out across client instances rather than a single connection. That is a different product shape from the usual one-database-one-server MCP integration, and it drives several of the design choices below.

How the server talks to Odoo: XML-RPC, JSON-2 and the tool surface

The transport to Odoo is version-dependent. According to the README, the server speaks XML-RPC for Odoo 16 through 18 and External JSON-2 for Odoo 19 and later. The README frames the JSON-2 support as preparation for the Odoo 22 removal of XML-RPC, so the version split is not cosmetic; it is the thing that keeps the server working across a migration.

On the agent side the surface is 41 tools plus 11 prompts in the self-hosted package. The tool list is wider than plain record reads. It includes server-side aggregation, chatter posting, schema inspection, domain building, addon scanning, upgrade-log diagnosis, data-quality checks, access-rule inspection, model-rename resolution, write validation, and cross-instance fan-out. Two accounting tools, `receivable_payable_aging` and `accounting_health_summary`, exist because those finance questions otherwise require hand-built domains.

Long reads do not block the conversation. `submit_async_task` runs operations such as addon scans, knowledge indexing and AR/AP aging on a bounded worker pool, and the agent polls `get_async_task` while continuing to reason. Knowledge search is local: `index_knowledge` and `search_knowledge` build a BM25 index over a bounded record slice, accent-insensitive and in-process, with no embeddings service and no data leaving the machine. That is a deliberate trade: BM25 over a slice is weaker than a vector index over everything, but it removes an external dependency and a data-egress question.

The surface is also trimmable. Tools can be shipped as separate pip packages through `odoo_mcp.tools` entry points and enabled with `ODOO_MCP_PLUGINS`, and `ODOO_MCP_TOOLS_INCLUDE` / `ODOO_MCP_TOOLS_EXCLUDE` cut the surface per deployment. Both are documented in `docs/plugins.md`.

Installing odoo-mcp and running a first read query

The README gives a one-line setup path through uv. The `--setup` flag is the interactive configuration step; it is what writes your Odoo connection details.

uvx odoo-mcp --setup

After that, the configuration lives in a file. The repository ships `odoo_config.json.example` for a single instance and `odoo_config.multi.json.example` for several, so the shape of the file is visible before you write it. The Dockerfile sets `ODOO_TIMEOUT`, `ODOO_VERIFY_SSL` and `DEBUG` as image defaults, and its comment states that runtime Odoo connection values should be supplied through `docker run -e ...` rather than baked into the image.

FROM python:3.10-slim
WORKDIR /app
RUN pip install --no-cache-dir .
ENV ODOO_TIMEOUT="30"
ENV ODOO_VERIFY_SSL="1"
ENV DEBUG="0"
ENV PYTHONUNBUFFERED=1
EXPOSE 8000
ENTRYPOINT ["odoo-mcp"]

That snippet is the repository's own Dockerfile, trimmed to the lines that matter for a first run. The image exposes port 8000, described in the Dockerfile as the default for Streamable HTTP when it is enabled. The entry point is `odoo-mcp`, the same console script declared in `pyproject.toml`. The package requires Python 3.10 or newer.

Once the server is registered with your client, the first useful call is a read. Ask the agent for customers in a country with unpaid invoices, or products under a stock threshold. Nothing in that path needs the write gate, and the results come back as ordinary tool output. If the agent returns an authentication error instead, the credentials or the database name are wrong, not the tool surface.

Writes sit behind an environment gate plus approval tokens, with optional MCP elicitation, as the README describes it. Do not enable that gate until you have run reads and are satisfied that the agent is seeing the records you expect.

What the write gate actually changes, and where it does not help

The gate is the most interesting design decision here and also the easiest to misread. An env gate plus approval tokens means the agent cannot turn a read into a write by rephrasing the request. The 11 prompts include six end-to-end business workflows (invoice approval, PO match, onboarding, expense review, month-end close, pre-migration data quality), and the README states those route writes through the gate. So the gate is not a bolt-on around the edges; the shipped workflows are built to pass through it.

What the gate does not do is decide whether a write is correct. It decides whether a write is permitted. An approval token is a human or client-side decision, and if the client auto-approves, the gate has done nothing except add a step. The hosted product is described as having a stronger posture here, with writes default OFF, a human-in-the-loop inbox, a journal, and field policy. The self-hosted server gives you the gate and an optional JSONL audit file, not the dashboard.

Field-level ACL is the other control, and it is opt-in per instance and per model, with allow and deny lists enforced on every read path including records, aggregates, the knowledge index and resources. The README claims this is the first open-source Odoo MCP with it, and the details are in `docs/field-acl.md`. Opt-in is the important word: if you do not configure it, an agent with a broad Odoo user sees what that user sees. The correct fix is a narrow Odoo user, and field ACL is the second layer, not the first.

Rate limiting follows the same pattern. It is opt-in, a sliding-window budget per instance and per tool, with `ODOO_MCP_RATE_LIMIT_MODE` set to `warn` or `block`, and the current state surfaces in `health_check`. Warn mode on a production database is a diagnostic, not a control.

When odoo-mcp is the wrong tool

The version floor is hard. Odoo 16 is the minimum, and the README does not describe a path for 15 or earlier. If you are on Odoo 15, this server is not a partial solution; it is not a solution.

The second limit is the client. This repository is the local and self-hosted server: stdio, or a local HTTP endpoint, run on your laptop, in Docker, or in CI. The README's comparison table lists Claude Code, Cursor and local agents as the clients for this repo, and ChatGPT as the primary client for the hosted ERPipe gateway. If your requirement is a stable remote MCP URL that ChatGPT can connect to without you running a process, the self-hosted server does not meet it, and the README says so directly rather than pretending otherwise.

The third limit is operational. A self-hosted MCP server is another process in your stack. It needs the Odoo credentials, it needs network reach to the Odoo instance, and if you run it in Docker you own the image, the port and the logs. The hosted gateway exists precisely to remove that, at the cost of sending your Odoo traffic through someone else's Cloudflare deployment. Neither choice is free; they trade different things.

Finally, the surface is wide. Forty-one tools is a lot of ways for an agent to be wrong, and the README does not document a rollback path for a write that was approved and then turned out to be incorrect. That is not a criticism of the gate. It is a gap a team should notice before enabling writes on a production database.

The hosted ERPipe gateway, and how it differs from self-hosting

ERPipe is the managed alternative from the same maintainer, and it is not a thin wrapper. The README lists 43 tools and 7 prompts on the hosted side against 41 tools and 11 prompts locally. The hosted side has fewer prompts and more tools, which fits its positioning: workspace multi-instance plus governance, with an explicit `instance` key per tool call and a dashboard-backed audit trail in D1.

The connection model is the real difference. Locally, multi-instance means a config file or environment variables on your machine. Hosted, it means signing up, adding HTTPS Odoo instances, and connecting once to `https://mcp.erpipe.com/mcp` with workspace OAuth. Writes are default OFF with a human-in-the-loop inbox, a journal, and field policy, which is a stronger default than the local env gate.

The README describes the hosted v1 as a free public beta with fair-use caps. That is a beta, and the README says so; anyone moving production finance workflows onto it should weigh that against the self-hosted server, which is MIT-licensed and free forever. The TypeScript building blocks live in a separate repository, `erpipe-org/erpipe`, if you want to see the hosted side's code rather than only its behaviour.

Licence, maintenance and the cost of upgrading

The package is MIT-licensed, declared in `pyproject.toml` and present as a `LICENSE` file at the repository root. MIT is permissive: you can modify, redistribute and use it commercially, and the only real obligation is carrying the licence text. That is the whole licence story here, and it is worth stating plainly because the hosted product is a separate commercial offering under its own terms.

Maintenance is visible in the repository rather than asserted. The last push was on 2026-08-25, and the repository is not archived. `pyproject.toml` declares version 1.3.2, so the version is in the source tree rather than only in release notes. The repository also carries a `CHANGELOG.md`, a `CONTRIBUTING.md`, a `SECURITY.md` and a `SUPPORT.md`, plus a CI workflow at `.github/workflows/publish.yml` that the README badge points at.

The upgrade cost is mostly the Odoo version boundary. Moving from Odoo 18 to 19 changes the transport from XML-RPC to External JSON-2, and the README presents the JSON-2 support as already in place for that reason. The dependency footprint is small: `mcp>=2,<3` and `requests>=2.31.0`, with Python 3.10 or newer. There is no database, no queue and no external service to operate for the self-hosted server, which keeps the upgrade surface narrow. The thing to watch is the tool surface itself. With 41 tools and plugin support through entry points, a deployment that enables third-party tools is adopting code the maintainer did not write, and `ODOO_MCP_PLUGINS` is the switch that decides whether that happens.

Editorial conclusion

Adopt odoo-mcp if you run Odoo 16 or newer, want the agent on your own machine or in Docker, and are willing to keep the write gate on. Skip it if your Odoo is older than 16, or if you need the agent reachable from ChatGPT without running a process, which is what the hosted ERPipe gateway exists for. Before rolling it out, verify three things against your own database: that the Odoo connection values in your config reach the instance, that the write gate stays off until you have tried the read tools, and that your Odoo user's ACLs match what you expect the agent to see.

Frequently asked questions

Official sources

1. erpipe-org/mcp-odoo on GitHub
2. Issues
3. License: MIT
4. Project website
5. README