odoo-mcp-server

A minimal, security-first MCP server that lets AI assistants (Claude Code, Claude Desktop, or any MCP client) read and — optionally, behind explicit allowlists — write to an Odoo 17 instance over XML-RPC.

Built and used in production-adjacent work: MRP cost analysis, simulated purchase→manufacture→sale flows, and inventory cleanup driven entirely through an AI assistant, with the blast radius controlled server-side.

Design goals

• Tiny, auditable surface: one file (server.py, ~450 lines), stdlib + the official mcp SDK only. No third-party business logic, no telemetry. The only network destination is your ODOO_URL.
• Read-only by default: write tools are not registered unless ODOO_ENABLE_WRITES=1 is set. There is no delete tool, ever.
• Allowlists all the way down:
  • models readable → ODOO_ALLOWED_MODELS (supports prefix.* wildcards)
  • models writable → ODOO_WRITE_MODELS (subset of the above)
  • fields writable per model → ODOO_WRITE_FIELDS
  • workflow methods callable → ODOO_ALLOWED_METHODS (exact model:method pairs)
• Defense in depth: these checks sit on top of the Odoo user's own access rights, which remain the primary boundary. See SECURITY.md for the full model.

Tools

Tool	Registered	Purpose
odoo_search_read	always	Search + read records (domain, fields, limit, order)
odoo_read	always	Read records by id
odoo_search_count	always	Count records matching a domain
odoo_fields_get	always	Introspect a model's fields
odoo_create	writes enabled	Create a record (model + field allowlists enforced)
odoo_write	writes enabled	Update records (model + field allowlists enforced)
odoo_call_method	writes enabled + method list non-empty	Run an allowlisted workflow method (confirm a PO, validate a picking, apply an inventory count, …)

Responses are hygienic by default: capped record counts, long/base64 values truncated, Odoo faults sanitized (no server tracebacks).

Installation

Requires Python 3.12+ and an Odoo 16/17 instance reachable over XML-RPC.

git clone https://github.com/rpl9717/odoo-mcp-server.git
cd odoo-mcp-server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

cp .env.example .env
chmod 600 .env
# edit .env: ODOO_URL, ODOO_DB, ODOO_USER, ODOO_API_KEY, allowlists

In Odoo, create a dedicated user with a restricted access-rights group and an API key (Settings → Users → My profile → Account security). Don't run this with an admin key outside of a supervised test.

Sanity-check the configuration and connection:

.venv/bin/python server.py --check   # auth + permission matrix
.venv/bin/python verify_mcp.py       # end-to-end suite over real stdio

Hooking it up to Claude Code

.mcp.json in your project (no secrets here — credentials live in .env next to server.py):

{
  "mcpServers": {
    "odoo": {
      "command": "/path/to/odoo-mcp-server/.venv/bin/python",
      "args": ["/path/to/odoo-mcp-server/server.py"]
    }
  }
}

One checkout can serve several databases: point ODOO_ENV_FILE at an alternate env file per server entry.

Configuration reference

See .env.example — every variable is documented inline, including the reasoning behind the field-level allowlist entries.

Security

See SECURITY.md: the layered security model, why a custom server instead of the community options, engineering notes (XML-RPC thread safety, None-marshaling quirk, driving TransientModel wizards over RPC), and the verification checklist.

License

MIT