Quickstart: the guided route¶

Start here: /odoo-tools:odoo-setup-mcp

Since v1.3.0 the plugin has a single guided route. Run /odoo-tools:odoo-setup-mcp (or its shortcut /setup-odoo-tools): it detects what you already have and walks you, one question at a time, through five phases:

1 Setup → 2 Verify → 3 Training → 4 Daily use → 5 Deployment

Each phase starts by showing where you are. This page summarizes the route in case you prefer to do it by hand.

New in v1.6.0

In Step 0, an odoo_version answer without a policy block stops the route: a copy older than 1.5.0 answered. In Claude Code, the route runs the copies check once, and the options check after you save.
In Step 0b, the route recognizes the status not_started with the reason user_config_unsupported as the Cowork and Claude chat case, offers you a local session of the Code tab (a cloud session does not have your options) and tells you that Claude Code needs no administrator rights.
In Step 3, the route first asks what the connection is for, and on Odoo Online it suggests the database from the subdomain.
The initial check also looks for git. On Windows, after you install Claude Code, Git or Python, you open a new PowerShell window.
Phase 5 gives the install command of each surface: inside Claude Code or in a terminal.

New in v1.5.1

In Step 0b, when the Odoo tools are not loaded, the route runs no command and checks no Python until it knows where you use Claude. In Cowork, a Python version read there belongs to its virtual machine, not to your computer.
/odoo-tools:odoo-doctor starts with the same check and ends with a support report you can send to Transgenia.

New in v1.5.0

Setup includes two new options: Permission profile (standard by default) and Permission policy file (optional). See Permission policy.
In the training, the write exercise archives the test contact instead of deleting it, because standard does not delete; the Studio-style exercise needs the builder profile.
Deployment recommends standard (or readonly) in production, and starting from the hardened example file when the Odoo user is an administrator.

Run the route in Claude Code

The route sets up and uses the Odoo tools, which run only in Claude Code on your computer (terminal, VS Code, JetBrains or a local session of the Code tab of Claude Desktop). In Cowork and Claude chat the skill loads but the tools do not: the route detects it in Step 0b and offers the path that works. See Where it works.

Phase 1: Setup¶

The route asks which case is yours:

Connect my Odoo (production or test): steps 0-4 below.
I have no Odoo to practice with / I don't want to touch production: start a local Odoo Community sandbox with /odoo-tools:deploy-local (Transgenia cannot provide Enterprise or Online instances). See Local deployment.
I can't install Python 3.9+: the MCP server as a container (/odoo-tools:deploy-local, container mode) or the CLI fallback.

Step 0: Detect what you already have¶

First it looks at its tool list, without running anything. If odoo_version is not there, the MCP server is not running on this surface: it goes to Step 0b before any shell command. If it is there, it calls it once and reads the answer before it says anything:

No policy and no note: an odoo-tools older than 1.5.0 answered, with no permission policy; it is often a second copy, installed from another place. The route stops there: no training, no daily use, no writes, and it helps you keep one current copy.
A note: the permission policy is locked. The note names the option or the file to fix; this is not a working connection.
plugin: the odoo-tools version that answered and its installed copy (plugin@marketplace). It shows it to you.

When it succeeds with a policy block, the plugin options are already configured: it shows you the version, edition and copy, and offers to skip to training, daily use or deployment. (It does not read ODOO_* variables or credential files from your machine to find out.)

When odoo_version answers, this is Claude Code on your computer, and the route runs the copies check once, even when everything works: two copies of odoo-tools can be active at once, and then the options dialog and the tools may belong to different copies. It shows you the output as it is: it names the copy to keep and gives the exact commands that remove the others (or that update an old copy from Transgenia's marketplace), which you run in a terminal (PowerShell or Terminal), never as /plugin commands, before you restart Claude Code. It never runs them in Cowork: there its commands reach a virtual machine, not your computer. See Two copies of odoo-tools.

Where it can run commands, it also checks whether python3 (3.9 or newer), git and docker are available, to know whether the Python route or the container route applies in the next phases.

Step 0b: Are the Odoo tools loaded?¶

Only when odoo_version does not exist as a tool. It does not start with Python. It asks where you use Claude: 1) Claude Code, 2) Cowork or 3) Claude chat. If you describe an empty panel on the odoo row labeled Runs in each session, under the plugin's Connectors tab, you are on 2 or 3. So are you if the app shows the plugin's server with the status not_started and the reason user_config_unsupported: the name Cowork and Claude chat give this case, the same on macOS and Windows, not a fault of the plugin or the app, and no update of the plugin changes it.

Claude Code: if the session itself runs in Anthropic's cloud (a cloud session of the Code tab, or Claude Code on the web), the options you saved on your computer are not there, so the server cannot start: the route offers you a local session, as in the offers under 2 or 3, and stops. Otherwise the server did not start; the usual causes are empty required options (URL, database, login) or a second copy of the plugin. If it can run commands, it runs the copies check of Step 0 and, once that names the copy to keep, the options check of that copy (Claude Code 2.1.285 or later; the output never shows the key). It acts on what they list: you enter the missing options in the options dialog, which you open inside Claude Code with /plugin configure <id>. If python3 is missing, neither check runs: the route reads claude plugin list --json directly (more than one odoo-tools@... id enabled here, or a version older than 1.5.0, is the problem; one id listed for two scopes is one copy, and a project or local entry counts only in its own folder, its projectPath or a folder inside it) and moves on to Python. Then you restart Claude.
Cowork or Claude chat: these apps do not run the plugin's local MCP server and have no form for its options. The install is fine, and nothing is wrong with your account, your Odoo or your Python; the route offers:
1. Claude Code on your computer (recommended): a terminal, VS Code, JetBrains, or a local session of the Code tab of Claude Desktop (not a cloud session, which lacks the options saved on your computer). A plugin installed on your Claude account appears there as a synced plugin at the next session start when you sign in to Claude Code (2.1.273 or later) with that claude.ai account; if it does not show, /reload-plugins or the commands in Installation. Claude Code needs no administrator rights: its native installer puts it in your home folder. On a Team or Enterprise plan your organization decides which plugins you get and whether the Code tab offers local sessions.
2. Cowork only: the fallback CLI, when the session can run Node, reach your Odoo, and you can edit its .env yourself. Use a dedicated, least-privilege, short-lived API key. Not for Claude chat, which has no safe place to enter the key.
3. Transgenia for assisted setup (see Support).

On those apps the route does not walk you through Python or the plugin options, because they cannot work there. In Cowork, shell commands run in a virtual machine, not on your computer: a Python version read there says nothing about your computer. Nor does it give Odoo-side advice (plan, API key, database) until the tools run and Odoo refuses the connection. If Claude's context has a line that starts with odoo-tools session diagnostics:, the plugin's session-start hook wrote it on your computer, and /odoo-tools:odoo-doctor turns it into a support report you can send to Transgenia.

Step 1: Choose the surface¶

MCP server (recommended): full tools + compatibility layer. It only needs python3 3.9+ on the PATH (no third-party dependencies; nothing is installed or downloaded at start).
Fallback CLI: lightweight, Node only. Use it if you cannot run the MCP.

If Python is missing, the route gives you the fix for your system. On Windows the command must be named python3 (see Requirements), and after you install Claude Code, Git or Python you open a new PowerShell window and restart Claude Code: a window opened before does not see the new PATH.

Step 2: Odoo version and edition (optional)¶

Community · Enterprise · Online (odoo.com/SaaS) · Not sure. The compatibility layer covers versions 10-19 automatically; this detail is only context.

Step 3: Connection details¶

Before the details, the route asks what the connection is for:

To learn or practice: the sandbox, preferably (Phase 1, option 2). With a real instance, it recommends Read-only mode on and the Permission profile readonly.
For real work: the Permission profile standard and Read-only mode on for the first days. Writes are turned on only when you confirm you want them.
Odoo URL: e.g. https://my-company.odoo.com (scheme + host, no trailing path).
Database name: Settings → Database, or visible in the login URL. On Odoo Online (*.odoo.com) it is usually the subdomain (my-company for https://my-company.odoo.com): the route suggests it and asks you to confirm.
Login email: the account you sign in with.
Credential: an API key (Odoo 14+, recommended) or a password (Odoo < 14). For the API key: Preferences → Account Security → New API Key (shown only once; copy it). On Odoo 19+ the API key is what enables JSON-2.

Odoo Online

On Odoo Online an API key is the only credential that works (users sign in through odoo.com, often with 2FA), and only Custom plans allow API access. From Odoo 18 keys expire: a user who is not an administrator gets at most 1 day, unless one of their groups allows longer. Note the expiry date; odoo_online_profile shows it later.

You type these values into the plugin's options dialog, not into the chat.

Security

Never paste the secret into the chat or write it into a file that the repository tracks. Use a least-privilege Odoo user for the agent. See Security.

Step 4: Persist the configuration¶

For the MCP server:

Run /plugin, open odoo-tools and choose Configure options (or /plugin configure <id>).
Fill in URL, database, login and API key (or password on Odoo < 14). Optional: Transport preference (auto by default: JSON-2 on Odoo 19+ with an API key; also json2, jsonrpc or xmlrpc), Request timeout (120 s by default), Read-only mode (recommended for the first days and for demos), Permission profile (standard by default: no deletes, no Studio-style changes, no email out except internal notes, no changes to users or rights and no stored secrets; also readonly, builder for sandboxes and staging, or full to keep the 1.4 behavior) and Permission policy file (optional: the absolute path to per-model rules, see Permission policy).
Restart Claude so the MCP server picks up the options.

The options dialog does not say which copy of the plugin it edits. If the copies check of Step 0 found more than one, the route fixes that first; after you save, it runs the options check on that copy and acts on what it lists.

On a remote or headless machine, claude plugin configure <id> --values-stdin saves the options without the dialog (see Installation). Pipe the JSON from a protected file or your secret manager; Claude never asks for, reads or echoes the key.

The API key and password are sensitive options: entered masked and kept in the operating system's secure credential store, not in settings.json or your shell profile. Do not export ODOO_* in ~/.bashrc/~/.zshrc or with setx for the plugin.

For the CLI, run /odoo-tools:odoo-setup-cli: it installs the CLI and creates a local .env in ~/.claude/tools/odoo-cli, readable only by your user, with placeholders. Paste the secret yourself in your own editor; Claude never asks for it in the chat.

Phase 2: Verify (definition of done)¶

MCP: call odoo_version. Its answer must carry plugin and policy: without policy, a copy older than 1.5.0 answered (go back to Step 0 and stop); with a note, the policy is locked (fix what it names and reconnect). Success = returns version + edition + deployment + transport, and the copy that answered (plugin.copy). On Odoo 19+ the transport should be json2; a transport_notice means the deprecated endpoints are in use (typically because no API key is set) and says how to fix it. Its policy block shows the active profile and the hidden tools. Then try: odoo_search_read { "model": "res.partner", "fields": ["name"], "limit": 1 }.
Odoo Online (deployment saas, or a saas~ version such as saas~19.2): also call odoo_online_profile and check the series, when your API key expires and the plan limits.
CLI: node ~/.claude/tools/odoo-cli/dist/cli.js contacts '{"limit":1}'.

If it fails, diagnose by the error:

odoo_version does not exist as a tool → the MCP server did not start. Follow Step 0b first: on Cowork and Claude chat it never starts, and the fix is not Python. On Claude Code, check the options, then python3 --version (3.9+), and restart Claude. On Windows, Failed to connect with Connection closed in claude mcp list is the sign of a missing python3; see Troubleshooting.
odoo_version answers without a policy block → a copy older than 1.5.0 answered; see Two copies of odoo-tools
authentication error → check DB / login / API key
transport error → check the URL (scheme + host)
"database not found" → check the exact database name
only odoo_version shows up and its policy block carries an error → the profile or the policy file is not valid and the server started locked; see Troubleshooting

Phase 3: Training (15-20 minutes, hands-on)¶

The route offers eight exercises. You type the request in your own words and Claude explains which tool answered and why. Exercises 1-5 are read-only; 6 to 8 write and are done only on the sandbox or a test database, asking for confirmation before each write.

Know your instance: "what version and edition of Odoo am I on?" → odoo_version, odoo_module_info.
Find records: "show me 5 customers from Mexico" → odoo_search_read with a domain.
Understand a model: "what fields does a sales order have?" → odoo_list_models, odoo_fields_get.
Summarize: "total invoiced per month this year" → odoo_read_group.
Export: "export active products to CSV" → /odoo-export.
Write with confirmation (sandbox/test): create a test contact, change its phone, then archive it → odoo_create, odoo_write (with {"active": false} to archive). Under the default profile standard deletes are refused and odoo_unlink is not listed: archiving is the reversible path. To practice a delete, set Permission profile to full on the sandbox (never on production) and reconnect (/mcp); then odoo_unlink removes the contact.
Low-code, Studio style (sandbox/test): a field or an automation → Studio-style. It needs the Permission profile builder (sandboxes and staging only).
Bulk import with a dry run (sandbox/test): "import these 3 contacts" → odoo_import_preview (Odoo checks every row and saves nothing) and, once you confirm, odoo_import (all rows or none). An id column holds external ids and updates the records that already have them.

Phase 4: Daily use¶

Need	Use
Ask about your data	just ask: the `odoo` agent and the MCP tools answer
Connection health check and support report	`/odoo-doctor`
Export records	`/odoo-export`
Differences across versions 10-19	`/odoo-tools:odoo-crossversion`
Fields and automations	`/odoo-tools:odoo-studio-style`
Plan a migration	the `odoo-migrator` agent
Sandbox: status, stop, start	`/odoo-tools:deploy-local status`
A machine without Python	`/odoo-tools:odoo-setup-cli` (CLI) or `/odoo-tools:deploy-local container`
Odoo Online: series, API key expiry, plan limits	`odoo_online_profile`
Why was a call refused? What may this user do?	`odoo_access_check`
A record's attachments or its stored invoice PDF	`odoo_record_documents`
Load many records at once	`odoo_import_preview` and, after confirmation, `odoo_import`
Parameter names of a method (JSON-2, `odoo_execute`)	`odoo_api_catalog`
Which permission profile is active and which tools it hides	`/odoo-doctor` or the `policy` block of `odoo_version`
Check a policy file offline	`--check-policy` (see Permission policy)

Good habits: keep Read-only mode on unless a task needs writes, confirm every write, and test bulk changes on the sandbox. When the odoo-tools permission policy refuses a call, the refusal is final: Claude explains it to you with the option that changes it, and does not look for another way (another tool, the fallback CLI or the shell). /odoo-doctor shows the active profile.

Phase 5: Deployment (team or production)¶

The route walks through this checklist with you:

One Odoo user per person, least privilege, with its own API key.
Read-only by default; writes only for those who need them. Keep the Permission profile at standard (or readonly) in production, builder only on sandboxes and staging, and full only where you decide to keep every right of the Odoo user. With an administrator user in production, start from a copy of ${CLAUDE_PLUGIN_ROOT}/docs/policy-examples/production-hardened.json kept outside every project (for example ~/.config/odoo-tools/policy.json, whose absolute path goes in Permission policy file) and check the copy first with python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-policy <file>. See Examples.
HTTPS URL and auto transport, unless there is a reason.
Pilot first: repeat the key workflows on the sandbox or a copy.
Backups before bulk writes or Studio-style changes.
Every machine installs the plugin once, from Transgenia's marketplace: inside Claude Code, /plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online; or in a terminal, claude plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online --scope user (on Claude Code older than 2.1.275, add the marketplace first). Then it runs the route, which checks that only one copy is active; machines without Python use container mode.
Updates from /plugin, reading the CHANGELOG before updating production users.
Odoo Online: plan the API key rotation (keys expire from Odoo 18; odoo_online_profile shows when), pace bulk work (about 1 call per second, imports of at most 500 rows per call) and expect a new saas~X.Y line every few months.

Support from Transgenia

At the points where it helps most (setup blocked, end of training, sandbox and deployment) the plugin reminds you that Transgenia provides maintenance, support, training and assisted deployment, through its official channels only: dev@transgenia.org · WhatsApp +52 55 8034 0405. See Support.