Odoo MCP

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

Why Odoo MCP

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:

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

Prefer a container? See Docker. For local development:

git clone https://github.com/tuanle96/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/tuanle96/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/tuanle96/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
• Cursor .cursor/mcp.json + agent rules: examples/cursor/
• Windsurf, VS Code, Zed, Continue.dev, Cline, Streamable HTTP, Docker: docs/client-configs.md
• Machine-readable install guide for agents (Cline-style): llms-install.md

Framework SDKs

Copy-paste-runnable integrations live in examples/:

Configuration reference

Set connection values in the environment:

export ODOO_URL="https://your-odoo-instance.com"
export ODOO_DB="your-database"
export ODOO_USERNAME="your-user"
export ODOO_PASSWORD="your-password-or-api-key"
export ODOO_TRANSPORT="xmlrpc"

For Odoo 19 JSON-2:

export ODOO_TRANSPORT="json2"
export ODOO_API_KEY="your-odoo-api-key"
export ODOO_JSON2_DATABASE_HEADER="1"

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.

Optional environment variables:

You can also use odoo_config.json:

{
  "url": "https://your-odoo-instance.com",
  "db": "your-database",
  "username": "your-user",
  "password": "your-password-or-api-key"
}

Multiple Odoo instances

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):

{
  "default": "acme",
  "instances": {
    "acme": {
      "url": "https://acme.odoo.com",
      "db": "acme",
      "username": "bot",
      "api_key": "...",
      "transport": "json2"
    },
    "globex": {
      "url": "https://globex.odoo.com",
      "db": "globex",
      "username": "bot",
      "password": "...",
      "lang": "fr_FR",
      "timeout": 60
    }
  }
}

• Every read/write tool accepts an optional instance parameter; omitted → the default instance. default itself is optional when only one instance is defined.
• 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.
• 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.
• 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.
• Instance names must match [A-Za-z0-9_-]{1,64}. Clients connect lazily — an instance is only contacted when a tool targets it.
• Discovery: the list_instances tool returns configured names, URLs, databases, and transports — never credentials.
• Write-approval tokens encode the instance name, so a token validated against one instance can never execute on another.
• MCP resources (odoo://…) always use the default instance in this release; use tools for multi-instance access.

Run

Start the MCP server over stdio:

odoo-mcp

or:

python -m odoo_mcp

Start Streamable HTTP for local clients:

odoo-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

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.

Check runtime posture without starting the server loop:

odoo-mcp --health

MCP Tools

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).

Read & Discover (11)

Write & Operate (5)

Diagnose (3)

Migrate (3)

Audit & Plan (3)

Knowledge search — local-first (3)

Accounting (2)

Background tasks (4)

Cross-instance fan-out — read-only (3)

One question across many configured instances, merged and attributed. See the partner playbook.

Utility (2)

Resources

Prompts

11 prompts: 5 diagnostic, plus 6 operational workflow prompts that encode end-to-end business processes and route every write through the approval gate.

Safe Write Model

Writes are intentionally boring.

1. preview_write creates a canonical, non-executing payload.
2. validate_write checks model metadata, required fields, readonly fields, relation hints, record IDs, and payload shape.
3. execute_approved_write runs only when all gates pass:
   • the approval came from validate_write in the same server process,
   • validation used trusted, non-empty live Odoo fields_get metadata,
   • the token has not expired or been consumed,
   • confirm=true is passed,
   • ODOO_MCP_ENABLE_WRITES=1 is set.

Odoo access rules, record rules, and server-side constraints still decide the final result.

Batch creates go through the same gates: pass values_list (one dict per record, max 100) to preview_write/validate_write — execution maps to a single atomic Odoo create(vals_list) call. Per-record differing write values are deliberately unsupported (they would need one non-atomic RPC per record). Optional extras: ODOO_MCP_ELICIT_WRITES=1 adds a native human-confirmation form, ODOO_MCP_AUDIT_LOG records every write-path event.

Reviewed side-effect methods such as sale.order.action_confirm can be enabled one by one:

export ODOO_MCP_ALLOWED_SIDE_EFFECT_METHODS="sale.order.action_confirm,res.partner.message_post"

ODOO_MCP_ALLOW_UNKNOWN_METHODS=1 is still supported for trusted deployments, but health_check reports it as broad mode. Prefer exact allowlist entries when you only need a small number of reviewed methods.

Docker

Use the prebuilt GHCR image:

docker pull ghcr.io/tuanle96/mcp-odoo:latest

Or build it locally:

docker build -t mcp/odoo:latest -f Dockerfile .

Run over stdio from an MCP client (replace mcp/odoo:latest with ghcr.io/tuanle96/mcp-odoo:latest to use the prebuilt image):

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "ODOO_URL",
        "-e", "ODOO_DB",
        "-e", "ODOO_USERNAME",
        "-e", "ODOO_PASSWORD",
        "-e", "ODOO_TRANSPORT",
        "-e", "ODOO_API_KEY",
        "mcp/odoo:latest"
      ]
    }
  }
}

Run Streamable HTTP locally:

docker run --rm \
  -p 127.0.0.1:8000:8000 \
  -e ODOO_URL \
  -e ODOO_DB \
  -e ODOO_USERNAME \
  -e ODOO_PASSWORD \
  -e ODOO_TRANSPORT \
  -e ODOO_API_KEY \
  mcp/odoo:latest \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --allow-remote-http

Test

Run the normal quality gates:

uv run python -m ruff check .
uv run python -m mypy src
uv run python -m pytest

Run real Odoo smoke tests:

uv run --python 3.12 --with-editable . scripts/odoo_compose_smoke.py \
  --versions 16.0 17.0 18.0 19.0 \
  --timeout 360 \
  --inspector-smoke

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.

Run the multi-instance smoke (one stack, three databases, two accounts on one instance):

uv run --python 3.12 --with-editable . scripts/odoo_multi_instance_smoke.py

Compatibility

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.

Documentation

Contributing

Issues, pull requests, and compatibility reports are welcome. Start with CONTRIBUTING.md, include your Odoo version, transport, client type, and the verification you ran.

Security

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.

License

MIT. See LICENSE.