# 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](docs/QUICKSTART.md)
- [Odoo authorization](docs/AUTHORIZATION.md)
- [Codex, Claude, Antigravity, and MCP client configuration](docs/CONFIGURATION.md)
- [Security policy](SECURITY.md)

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

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

For the current local checkout:

```bash
cd /Users/osamahalnihmi/odoo-mcp
```

Create an isolated Python environment and install the server:

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

Windows PowerShell:

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

The MCP command is:

```text
/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:

```text
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:

```text
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:

```text
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`:

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

```bash
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:

```json
{
  "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/`](config).

## Install The Built-In Skill

The repository includes the portable
[`odoo-website-theme-design`](skills/odoo-website-theme-design) skill.

Codex:

```bash
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:

```bash
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:

```text
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:

```text
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

```bash
.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`](skills/odoo-website-theme-design).