odoo-mcp-multi

MCP server and CLI that connects AI clients (Antigravity, Claude Desktop, Cursor, VS Code) to one or more Odoo instances. It exposes 12 tools for searching, counting, creating, updating, deleting, exporting, and importing records through the Model Context Protocol. No Odoo module installation required. Works with Odoo 8.0 through 19.0+.

What Problem Does This Solve

Other Odoo MCP servers require you to set environment variables for a single Odoo instance. When you work with multiple environments (production, staging, development, client instances), you must stop the server, change the variables, and restart.

odoo-mcp-multi solves this with named profiles stored in a local config file. Each profile holds its own URL, database, and credentials. Any tool call or CLI command can target a different profile with a single --profile / -p flag — no server restart, no env var juggling. The server auto-detects which RPC protocol to use (XML-RPC for Odoo 8–18, JSON-RPC, or JSON/2 REST for Odoo 19+) based on the target instance version.

Every MCP tool is also available as a CLI command with identical logic and output format. This means you can script Odoo operations in bash, pipe JSON through jq, and automate workflows without writing Python.

Features

• Multi-profile management — store credentials for prod, staging, dev (or any name) and switch with -p
• Auto protocol detection — XML-RPC (8.0+), JSON-RPC, JSON/2 REST (19.0+) selected automatically per profile
• Secure credential storage — ~/.config/odoo-mcp/profiles.json with Unix 600 permissions (owner-read-only)
• 13 MCP tools — search_read, search_count, write, unlink, create, export_records, import_records, execute_kw, list_models, list_fields, list_available_profiles, get_version, get_financial_report
• Full CLI parity — every MCP tool works as a terminal command with JSON output, composable with jq and shell scripts
• One server for every session — odoo-mcp serve --auth local serves every MCP client on a workstation from one process with your profiles.json, instead of one ~60 MiB process per session; loopback only, bearer token in a 0600 file next to profiles.json (guide)
• Remote connector mode — odoo-mcp serve exposes the same tools over HTTP with a built-in OAuth 2.1 server; each user signs in with their own Odoo credentials and every call runs under their own access rights (guide)
• Agentic skills — ships three installable skills for AI agents (odoo-mcp plugins install <agent>)
• No Odoo module required — connects through standard XML-RPC or the native /json/2 REST API

How It Differs From Other Odoo MCP Servers

1-Minute Setup (Copy-Paste Prompts)

Paste the blocks below into your AI client (Antigravity, Claude, Cursor) to get started.

1. Install the Package

Please install the `odoo-mcp-multi` package with whichever of these tools I already have — any of them is fine:
- uv:   `uv tool install odoo-mcp-multi`, then `uv tool update-shell`
- pipx: `pipx install odoo-mcp-multi`, then `pipx ensurepath`
- pip:  `pip install odoo-mcp-multi` inside a Python environment I already manage
- Or install nothing: MCP clients can launch it with `uvx --from odoo-mcp-multi odoo-mcp run`.

uv and pipx put `odoo-mcp` in ~/.local/bin, which is not on PATH until that second command runs AND a new terminal is opened. If `odoo-mcp` is still "not found", use its absolute path (`uv tool dir --bin` or `pipx environment --value PIPX_BIN_DIR` prints the directory).

After installing, please run `odoo-mcp add-profile` to configure my credentials interactively, and then run `odoo-mcp test` to verify the connection.

2. Configure MCP

Please configure the `odoo-mcp` server in my MCP client settings.
Add the following block to my configuration file (e.g. `mcp_config.json` for Antigravity, or `claude_desktop_config.json` for Claude):

{
  "mcpServers": {
    "odoo": {
      "command": "odoo-mcp",
      "args": ["run"]
    }
  }
}

Once added, remind me to restart my AI client so I can use the 11 Odoo tools available.

3. Install Agentic Skills

Please install the agentic skills bundled with the `odoo-mcp` package.
Run the command `odoo-mcp plugins install <agent_name>` where `<agent_name>` is your own identity (e.g., `antigravity`, `agy`, `agents`, `codex`, `opencode`, `kimi`, or `hermes`).
This will copy the skills into my global skills directory so you can use them in future tasks.

3b. Claude Code: install as a plugin

Claude Code consumes odoo-mcp as a standard plugin from the Vauxoo AI marketplace — skills plus the odoo MCP server in one install (the MCP server runs the installed odoo-mcp CLI from PATH, so install the package first):

/plugin marketplace add https://git.vauxoo.com/ai/marketplace.git
/plugin install odoo-mcp@vauxoo-ai

If you previously ran odoo-mcp plugins install claude, run it again: it now offers to remove the old flat copies and prints these commands.

Installation

Four installers work, and none is preferred: use the one you already have. Every merge request installs the built wheel with each of them on Python 3.10 and 3.14, launches the MCP server the way a client does and runs odoo-mcp upgrade; every release repeats that against PyPI.

odoo-mcp upgrade detects which of these installed it and runs the matching command (under uvx it explains the @latest refresh instead).

Getting the installer itself:

uv downloads a Python interpreter when none is installed, so on a clean machine it is the shortest path. Then configure and run:

odoo-mcp add-profile
odoo-mcp test
odoo-mcp run

The extra PATH step (uv tool, pipx and uvx)

uv tool install and pipx install put odoo-mcp in an isolated environment and link it into ~/.local/bin (%USERPROFILE%\.local\bin on Windows). That directory is usually not on PATH, so right after a successful install the shell answers odoo-mcp: command not found ("is not recognized" on Windows). The uv installer puts uv and uvx in the same directory, so the same applies to uvx. This is expected, and CI checks both halves: the command is missing after install, and found after the step below in a new shell.

1. Add the directory once: uv tool update-shell or pipx ensurepath, then open a new terminal. The current one keeps the old PATH.
2. Or skip PATH and use the absolute path, which uv tool dir --bin or pipx environment --value PIPX_BIN_DIR prints.

MCP clients launched from the Dock, Finder or Start menu (Claude Desktop, Antigravity) do not read your shell's rc files, so on macOS they may still not find odoo-mcp or uvx after step 1. Put the absolute path in the client's command (see MCP Client Configuration).

Windows

Windows notes:

• Not covered by CI: the install jobs run on Linux. The support runbook docs/windows-install.md covers the Windows-only failures (Smart App Control, pip not on PATH).
• Credential file permissions: on Linux/macOS, credentials are stored with 600 (owner-read-only) Unix permissions. On Windows, os.chmod is silently ignored — the file %USERPROFILE%\.config\odoo-mcp\profiles.json is created correctly but without restricted permissions. Ensure your user account is the only account with access to your machine.
• Python from python.org: also works, but during installation you must check "Add Python to PATH" (unchecked by default). Without it, pip won't be found.
• Microsoft Store Python: avoid it — it runs in an app sandbox that can cause issues with pipx ensurepath and file system access.

Uninstall

Use the uninstall command from the table above for the installer you used.

Credentials are not removed automatically. Delete the profile file manually if needed:

• macOS / Linux: ~/.config/odoo-mcp/profiles.json
• Windows: %USERPROFILE%\.config\odoo-mcp\profiles.json

Profile Management

Profiles define how odoo-mcp connects to each Odoo instance. Each profile stores a URL, database name, and authentication credentials (user/password for Odoo < 19, or an API key for Odoo 19+).

# Interactive wizard (prompts for all fields)
odoo-mcp add-profile

# Non-interactive — Odoo < 19 (XML-RPC / JSON-RPC, user + password)
odoo-mcp add-profile --name prod --url https://odoo.example.com \
  --database mydb --user admin --password secret

# Non-interactive — Odoo 19+ (JSON/2 REST, API key)
odoo-mcp add-profile --name prod19 --url https://odoo19.example.com \
  --database mydb --api-key YOUR_API_KEY --protocol json2s

CLI Operations

All data commands support --profile / -p and output JSON for composability.

MCP Client Configuration

The server handles multiple Odoo instances simultaneously. You only need to declare one server definition in your AI client. To force a single default profile, use ["run", "-p", "prod"].

{
  "mcpServers": {
    "odoo": {
      "command": "odoo-mcp",
      "args": ["run"]
    }
  }
}

With uvx nothing is installed, and the client starts the server from uv's cache:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["--from", "odoo-mcp-multi", "odoo-mcp", "run"]
    }
  }
}

If the client reports that odoo-mcp or uvx is not found, it does not see the directory the installer used (see the extra PATH step). Replace command with the absolute path, e.g. /Users/you/.local/bin/odoo-mcp (command -v odoo-mcp on macOS/Linux, where.exe odoo-mcp on Windows).

Add the block to your client's MCP config file. Paths vary by tool and OS:

Note: For Cursor and VS Code the config file is workspace-scoped — place it at the root of your project. For a user-level (global) config, check your client's own documentation.

Sandbox Execution Rail

When running odoo-mcp CLI commands inside sandboxed AI agent environments (Antigravity, Claude Code, Cursor, Windsurf, OpenHands, Aider), CPython bootstrap may fail with:

• Fatal Python error: init_import_site OR PermissionError: .../pyvenv.cfg

This occurs because CPython requires read access to pyvenv.cfg outside the workspace boundary. For machine-readable directives that halt token-wasting retry loops and grant least-privilege target paths (~/.local/pipx/venvs/odoo-mcp-multi/ or ~/.local/share/uv/tools/odoo-mcp-multi/), see AGENT.md.

Available MCP Tools

All tools accept an optional profile string parameter to select the target Odoo environment dynamically.

Usage Examples

"List all contacts containing 'John' in their name"

search_read(model="res.partner", domain="[('name', 'ilike', 'John')]", fields="name,email,phone")

"Create a new contact named Alice with email alice@example.com"

create(model="res.partner", values='{"name": "Alice", "email": "alice@example.com"}')

"Delete archived partners"

unlink(model="res.partner", ids="[10, 11, 12]")

"Confirm the sales order with ID 42"

execute_kw(model="sale.order", method="action_confirm", args="[[42]]")

"What fields does the invoice model have?"

list_fields(model="account.move")

"Export the name and external ID of all active partners"

export_records(model="res.partner", domain="[('active', '=', True)]", fields="id,name")

"Update the phone number of the partner with external ID 'base.res_partner_1' and create a new partner"

import_records(model="res.partner", fields="id,name,phone", rows='[{"id": "base.res_partner_1", "name": "Existing Partner", "phone": "12345"}, {"name": "New Partner", "phone": "67890"}]')

Security and Development

• Credentials are written to ~/.config/odoo-mcp/profiles.json with 600 Unix permissions (owner-read-only). Passwords and API keys use Pydantic SecretStr to prevent accidental logging.
• Development mode: pip install -e ".[dev]". Code quality is enforced by ruff (line length 119, mccabe complexity ≤ 15).
• Tests: pytest with --cov (290+ tests, 86%+ coverage).

  Maintained by Nhomar Hernández at Vauxoo — Odoo Gold Partner.  ·  Report an Issue