Odoo MCP server

Odoo MCP

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

odoo-mcp is a workflow-native MCP server for Odoo Enterprise. It exposes read-only capability discovery, trial-balance reporting, aged receivables and payables reporting, cashbook visibility, unmatched bank-line detection, and proposal-only bank reconciliation.

The initial accounting release also supports bounded invoice, supplier-bill, credit-note, payment-registration, and manual-journal workflows. Mutating tools are preview-only by default and require explicit execution plus idempotency.

The internal accounting adapter provides bounded, typed, company-scoped read primitives for the reporting workflows. It enforces fixed model/action allowlists, strips denied fields, normalizes dates, decimals, relations, and cursor pages, and translates Odoo authentication, permission, and transport failures into safe errors. It does not expose generic CRUD or an Odoo configuration surface.

Supported connection targets are Odoo.sh and self-hosted Odoo Enterprise:

• Odoo 18 through external JSON-RPC
• Odoo 19 through JSON-2

Other Odoo versions, Odoo Online, Community edition, and custom forks are not supported. This package is not an Odoo module and does not expose generic model CRUD.

Installation

The product and commands are named odoo-mcp; the PyPI distribution is odoo-erp-mcp because the odoo-mcp distribution name is owned by another project.

pipx install odoo-erp-mcp
odoo-mcp --help

The package also exposes odoo-erp-mcp as a compatibility launcher for MCP Registry clients. It starts the same server as odoo-mcp.

Local Development

Requires Python 3.11 or newer and uv.

Copy-Item .env.example .env.local
# Replace the placeholders in .env.local, then:
uv sync --locked --all-extras
uv run odoo-mcp --profile local --config config/config.example.yaml

Local Development uses stdio. Process-environment settings take precedence over .env.local. Never commit .env.local.

Remote profiles

Dedicated Remote and Shared Hosted use the same server, registry, workflow, and Odoo adapter as Local Development, exposed through Streamable HTTP:

uv run odoo-mcp --profile dedicated --host 127.0.0.1 --port 8000
uv run odoo-mcp --profile shared --host 127.0.0.1 --port 8000

Dedicated Remote reads its single Odoo connection from the process environment; it never loads .env.local. Every /mcp request must carry a deployment-issued HS256 bearer JWT. The server validates its signature, fixed issuer, fixed audience, expiry, issued-at time, subject, and client ID before MCP routing; permissions and company grants remain server-owned. Configure ODOOMCPAUTHISSUER, ODOOMCPAUTHAUDIENCE, and a secret-store supplied ODOOMCPAUTHSIGNINGKEY of at least 32 characters.

Shared Hosted is a runnable open-enrollment application in the same image. It serves OAuth discovery, dynamic client registration, authorization, token, revocation, browser enrollment, protected-resource metadata, and MCP routes. The application verifies each Odoo connection, lets the user select from the companies that Odoo returned, stores the credential encrypted, and binds every token to exactly one active connector. Configure it from .env.shared.example; its versioned 256-bit encryption keys must come from an operator-controlled secret store. Missing configuration, invalid ciphertext, inactive grants, unsafe Odoo destinations, and unauthorized connector bindings fail closed. Shared Hosted supports either one writable process with a durable local SQLite volume or qualified PostgreSQL with pooled runtime and direct migration connections. TLS, public ingress, monitoring, and production deployment remain operator responsibilities.

Shortened. The full README is on GitHub.