Odoo MCP

Safety-first Model Context Protocol server for Odoo 16, 17, 18, and 19. It uses standard MCP transports, so it can be connected to Codex, Claude Code, Google Antigravity, Gemini, and other MCP clients.

What It Does

Odoo MCP lets an AI assistant safely inspect Odoo records, explain business data, inspect model fields, prepare controlled changes, record those changes, and roll supported changes back.

Typical uses include:

• Accounting review and exception reporting
• Implementation and configuration inspection
• Audit queries and MCP change-history review
• Website page, menu, view, and theme work
• Safe, approved updates to supported Odoo records

Documentation

• Quick start
• Odoo authorization
• Codex, Claude, Antigravity, and MCP client configuration
• Security policy

Requirements

• Python 3.10 or newer
• Odoo 16, 17, 18, or 19
• An Odoo user permitted to use the required applications and records
• An API key generated for that Odoo user
• An MCP-compatible client such as Codex, Claude Code, or Antigravity

Use a dedicated Odoo bot user. Do not connect the main administrator account.

Installation

Clone the repository after it is published:

git clone https://github.com/techniondigitalsolutions/odoo-mcp.git
cd odoo-mcp

For the current local checkout:

cd /Users/osamahalnihmi/odoo-mcp

Create an isolated Python environment and install the server:

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

Windows PowerShell:

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .

The MCP command is:

/absolute/path/odoo-mcp/.venv/bin/python -m odoo_mcp.server

Always use an absolute path in the AI client's configuration.

Odoo Authorization

Create a dedicated Odoo user such as:

Name: Odoo MCP Bot
Login: odoo-mcp@example.com

Grant only the minimum access groups required for its job:

• Auditor: read access to the applications being reviewed
• Accountant assistant: required accounting read access
• Implementer: access only to relevant implementation areas
• Website editor: minimum website editing permissions

Then generate an API key:

1. Sign in as the dedicated user.
2. Open the user menu and select Preferences or My Profile.
3. Open Account Security.
4. Select New API Key.
5. Use a description such as Odoo MCP - laptop.
6. Select the shortest practical expiration.
7. Generate and securely store the key.

Odoo normally displays the complete key only once. Never commit it to Git or paste it into prompts, screenshots, issues, skills, or documentation.

Environment

Every MCP client configuration must provide:

ODOO_URL=https://your-company.odoo.com
ODOO_DATABASE=database-name
ODOO_USERNAME=odoo-mcp@example.com
ODOO_API_KEY=your-private-api-key
ODOO_API_MODE=auto
ODOO_ALLOW_MUTATIONS=false

ODOO_API_MODE=auto selects XML-RPC for Odoo 16-18 and JSON-2 for Odoo 19. Keep mutations disabled until read operations and Odoo permissions are tested.

Optional limits:

ODOO_MAX_READ_RECORDS=100
ODOO_MAX_MUTATION_RECORDS=20
ODOO_PLAN_TTL_SECONDS=300
ODOO_JOURNAL_PATH=~/.local/state/odoo-mcp/journal.sqlite3

Codex Configuration

Add this to the user Codex configuration, normally ~/.codex/config.toml:

[mcp_servers.odoo]
command = "/absolute/path/odoo-mcp/.venv/bin/python"
args = ["-m", "odoo_mcp.server"]

[mcp_servers.odoo.env]
ODOO_URL = "https://your-company.odoo.com"
ODOO_DATABASE = "database-name"
ODOO_USERNAME = "odoo-mcp@example.com"
ODOO_API_KEY = "your-private-api-key"
ODOO_API_MODE = "auto"
ODOO_ALLOW_MUTATIONS = "false"

Restart Codex after saving the configuration.

Claude Code Configuration

Register the local server:

claude mcp add odoo \
  --env ODOO_URL=https://your-company.odoo.com \
  --env ODOO_DATABASE=database-name \
  --env ODOO_USERNAME=odoo-mcp@example.com \
  --env ODOO_API_KEY=your-private-api-key \
  --env ODOO_API_MODE=auto \
  --env ODOO_ALLOW_MUTATIONS=false \
  -- /absolute/path/odoo-mcp/.venv/bin/python -m odoo_mcp.server

Restart Claude Code after registering the server.

Antigravity And Other MCP Clients

Add a local stdio server through the client's MCP settings:

{
  "servers": {
    "odoo": {
      "type": "stdio",
      "command": "/absolute/path/odoo-mcp/.venv/bin/python",
      "args": ["-m", "odoo_mcp.server"],
      "env": {
        "ODOO_URL": "https://your-company.odoo.com",
        "ODOO_DATABASE": "database-name",
        "ODOO_USERNAME": "odoo-mcp@example.com",
        "ODOO_API_KEY": "your-private-api-key",
        "ODOO_API_MODE": "auto",
        "ODOO_ALLOW_MUTATIONS": "false"
      }
    }
  }
}

Client configuration formats vary. The required concept is always a local stdio command, argument list, and private per-server environment variables. Additional examples are available in config/.

Install The Built-In Skill

The repository includes the portable odoo-website-theme-design skill.

Codex:

ln -s /absolute/path/odoo-mcp/skills/odoo-website-theme-design \
  ~/.codex/skills/odoo-website-theme-design

Claude Code and the current local Antigravity build:

ln -s /absolute/path/odoo-mcp/skills/odoo-website-theme-design \
  ~/.claude/skills/odoo-website-theme-design

On systems without symlink support, copy the complete skill directory instead.

Test The Connection

Restart the AI client and ask:

Use odoo_connection_info and report the Odoo version, protocol, mutation status, and rollback scope.

The initial result should show mutations_enabled: false.

Then test a small read:

Use odoo_search_read on res.company, request only name, and return at most five records.

If access is denied, adjust the dedicated Odoo user's permissions rather than switching to an administrator account.

Enable Safe Changes

Change the client environment only after read-only testing succeeds:

ODOO_ALLOW_MUTATIONS=true

Restart the client. Supported changes follow this sequence:

1. The AI calls preview_odoo_mutation.
2. You review the exact model, record IDs, and values.
3. You explicitly approve the change.
4. The AI calls apply_odoo_mutation with the single-use preview token.
5. The MCP journals the previous state and verifies the result.
6. The MCP returns a change_id.

Keep the change_id when the change may need to be reversed.

Rollback

Ask the AI to call:

rollback_change(change_id)

Rollback currently restores supported scalar-field writes and removes records created through this MCP. It refuses to overwrite records changed again after the original MCP operation.

Rollback cannot reverse sent emails, webhooks, payments, custom automation side effects, or changes made outside this MCP. Maintain normal Odoo database backups.

Safety Model

• Read-only by default: set ODOO_ALLOW_MUTATIONS=true to enable changes.
• No generic method execution and no direct delete tool.
• Sensitive models and fields are blocked or redacted.
• Every mutation requires a short-lived preview token.
• An owner-only local snapshot is journaled before each change.
• Every action is written to a local SQLite audit journal.
• rollback_change restores writes and removes records created by this MCP.
• Rollback refuses to overwrite records changed again after the MCP operation.
• Record counts, fields, models, and values are bounded by policy.

Rollback covers Odoo records changed through this server. It does not replace database backups and cannot reverse external side effects such as sent email, webhooks, payment operations, or custom automation triggered by a write. The initial rollback engine permits scalar-field writes only; relational field changes require a future relation-aware snapshot format.

Credentials are read only from environment variables and are never returned by tools or stored in the journal.

Troubleshooting

Authentication Failed

• Verify that the login belongs to the API key's user.
• Confirm that the key is complete, active, and unexpired.
• Confirm that the URL and database belong to the same Odoo instance.

Access Denied

Authentication succeeded, but the dedicated user lacks a required access group, model permission, or record-rule permission. Grant only the missing access.

MCP Server Does Not Appear

• Use an absolute Python path.
• Confirm installation with .venv/bin/pip show odoo-mcp.
• Restart the AI client.
• Check that the client's JSON or TOML syntax is valid.

Changes Are Disabled

This is the expected default. Review the authorization and rollback behavior before setting ODOO_ALLOW_MUTATIONS=true.

Development

.venv/bin/python -m unittest discover -s tests
.venv/bin/ruff check .
.venv/bin/python -m compileall src

The bundled website skill is in skills/odoo-website-theme-design.