跳转至

安装

v1.6.0 新增

  • 按环境区分的安装命令： 在 Claude Code 中用 /plugin install ...，在终端中用 claude plugin install ... --scope user。在 PowerShell 中输入 /plugin 命令会失败。参见 作为 Claude 插件。
  • 两个 odoo-tools 副本： 有哪些迹象，以及只保留一个最新副本的副本检查与选项检查。参见 两个 odoo-tools 副本。
  • odoo_version 会点名作出响应的副本（plugin 块）。参见 验证。
  • Windows： 没有 python3 命令时，claude mcp list 会把服务器报告为 Failed to connect 并带有 Connection closed。修正它的 PowerShell 命令见 要求。
  • not_started 状态与本地会话： 状态 not_started、原因 user_config_unsupported 是 Cowork 和 Claude chat 的情况，任何更新都不会改变它。请使用 Code 标签页中的本地会话或你电脑上的 Claude Code；Claude Code 不需要管理员权限。参见 作为 Claude 插件。
  • Docker： Odoo 14.0 至 19.0 的沙箱为插件提供 API key（参见 本地部署），容器模式的镜像为 ghcr.io/transgenia/odoo-mcp-tools:1.6.0。

v1.5.1 新增

  • 新的会话开始 hook hooks/session_start.py，取代 hooks/check_options.py：它不读取任何插件选项或凭据。当最近 14 天既没有记录到与 Odoo 的成功连接，也没有记录到带齐全部连接设置的服务器启动时，它会说明 Odoo 工具在哪里运行。参见 验证。
  • 本地诊断： 服务器把元数据写入 ${CLAUDE_PLUGIN_DATA}/diagnostics（ODOO_DIAG_DIR），/odoo-tools:odoo-doctor 会把它整理成一份支持报告。参见 支持。
  • 凭据： 服务器不再读取 ODOO_HTTP_BEARER；它只读取插件选项传给它的 API key 或密码。
  • Docker： /odoo-tools:deploy-local 的容器模式会在插件的数据文件夹中留下标记，让该 hook 保持沉默；其镜像为 ghcr.io/transgenia/odoo-mcp-tools:1.5.1。

v1.5.0 新增

默认安全的权限。要保留 1.4 的行为，请把 Permission profile 选项设为 full。

  • 两个新选项，都有默认值：Permission profile（standard；也可选 readonly、builder 或 full）和 Permission policy file（为空，或一个按模型定义规则的 JSON 文件的绝对路径）。参见 权限策略。
  • Read-only mode 现在会隐藏写入工具（调用其中一个仍会说明为什么被拒绝）。
  • 审计日志： 服务器在插件的数据文件夹（${CLAUDE_PLUGIN_DATA}/audit）中为每次工具调用写一行，并保留 90 天。
  • 用 --check-policy 离线检查 策略文件。
  • Docker： 环境文件可以设置策略和审计文件夹；基于请求头的多租户路径已被移除。
  • 容器模式的镜像为 ghcr.io/transgenia/odoo-mcp-tools:1.5.0。

v1.4.1 新增

文档与诊断版本：MCP 服务器的行为没有变化。

  • 一步安装： /plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online（Claude Code 2.1.275 或更高版本）。在更早的版本中，原来的两条命令仍然有效。
  • 工具在哪里运行： Odoo 工具在 Claude Code 中运行；Cowork 和 Claude chat 会加载 skills 和命令，但不加载这些工具。参见 适用环境。
  • 会话开始时提示缺失的选项： 第二个 SessionStart hook 会告诉你哪些必需选项（URL、数据库、登录名）还没有保存值。它从不读取 API key 或密码。参见 安全。
  • 无对话框配置： claude plugin configure（Claude Code 2.1.285 或更高版本），适用于远程或无界面的电脑。
  • Windows： 会话开始的 hooks 需要 Git Bash（参见 要求）。
  • 容器模式的镜像为 ghcr.io/transgenia/odoo-mcp-tools:1.4.1。

v1.4.0 新增

  • 28 个工具： 新增六个面向 Odoo Online 的工具，在任何 Odoo 10-19 上都可用（odoo_online_profile、odoo_api_catalog、odoo_access_check、odoo_record_documents、odoo_import_preview、odoo_import）。参见 工具参考。
  • JSON-2 传输： 在配置了 API key 的 Odoo saas~18.4 / 19.0+ 上，auto 模式会使用 Odoo 新的 JSON-2 API，因为 Odoo 22 和 Odoo Online saas~21.1 会移除 /xmlrpc 和 /jsonrpc。Transport preference 新增 json2 选项。参见 兼容性。
  • odoo_read_group 自 saas~18.4 起使用 formatted_read_group，并保留其经典输出。
  • Odoo Community 10.0 至 19.0 的沙箱（之前为 16.0 至 19.0）。参见 本地部署。
  • 已修复： 使用错误的 API key 或密码时，odoo_version 不再报告成功；HTTP 429 不再切换传输方式。

v1.3.0 新增

  • 引导路线： /odoo-tools:odoo-setup-mcp 带你完成配置、验证、培训、日常使用与部署。参见 快速开始。
  • 本地基础设施： /odoo-tools:deploy-local 在 Docker 上启动 Odoo 16-19 沙箱，或为没有 Python 的电脑以容器方式运行 MCP 服务器（ghcr.io/transgenia/odoo-mcp-tools）。参见 本地部署。
  • Release 与软件包： 每个版本都会作为 GitHub Release（插件 zip + sdist/wheel）以及 GHCR 镜像发布。
  • 支持： 连接错误会说明如何修复以及联系谁。更新时无需重新配置。

v1.2.0 变更

从 1.2.0 版本开始，MCP 服务器 不再使用 uv（也不再使用 uv run --frozen）。插件直接用 python3 从随附的源代码启动它，运行时没有任何第三方依赖（仅使用 Python 标准库）：启动时不安装、不下载任何东西，server/uv.lock 也已删除。你无需重新配置任何内容：已填写的插件选项会保留；只需在 PATH 中提供 python3 3.9 或更高版本 来代替 uv（见下文的 要求）。此外：

  • 超时： ODOO_TIMEOUT 的默认值从 30 秒提高到 120 秒（Odoo 默认的 limit_time_real），并且现在是插件选项 Request timeout。XML-RPC 也会遵循它：以前，无响应的 Odoo 可能会让 XML-RPC 调用无限期阻塞。
  • 全部 9 个 skills 和命令现在都能加载。 以前，位于 skills/ 根目录的 skills/SKILL.md 让 6 个 skills 中的 5 个被隐藏，因此 /odoo-tools:odoo-setup-mcp 并不存在。
  • 修复了 Community 实例上 odoo_version 的 死锁。
  • 工具参数会按各工具的模式（schema）校验：不匹配时，调用会在到达 Odoo 之前以 Input validation error: ... 被拒绝。
  • 在 auto 模式下，写入在超时或 HTTP 5xx 之后绝不会通过 XML-RPC 重放：错误会说明该调用 "may or may not have been applied"（可能已应用，也可能未应用）。参见 故障排查。

v1.1.0 变更 / 迁移

从 1.1.0 版本开始，插件通过 插件选项（userConfig）进行配置，不再读取 你 shell 中的 ODOO_* 环境变量。如果你在 v1.0.0 中曾在 ~/.bashrc、~/.zshrc 或通过 setx 导出了 ODOO_*，请在 /plugin → odoo-tools → Configure options 中 一次性 填入这些值（之后可以将它们从 shell 配置文件中删除）。独立（standalone） 服务器（Docker、python -m odoo_mcp）仍然读取 ODOO_* 变量。

作为 Claude 插件（推荐）

只安装一次，从 Transgenia 的 marketplace 安装，并且只用以下两种方式中的 一种。

在 Claude Code 中（在会话中输入）：

/plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online
/odoo-tools:odoo-setup-mcp

在终端中（PowerShell、Terminal 或 bash），适用于你的所有文件夹：

claude plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online --scope user

然后启动 Claude Code 并输入 /odoo-tools:odoo-setup-mcp。/plugin 命令只在 Claude Code 中输入，绝不在终端中输入：在 PowerShell 中输入时，它会以“无法识别”（not recognized）的错误失败。claude plugin 命令在终端中输入，绝不在聊天中输入。在 Windows 上，如果刚安装 Claude Code 后无法识别 claude，请打开一个新的 PowerShell 窗口（参见 要求）。

第一种方式一步完成添加 marketplace 并安装插件（Claude Code 2.1.275 或更高版本）。在没有 --marketplace 选项的更早版本的 Claude Code 中，请先在 Claude Code 中添加 marketplace：

/plugin marketplace add Transgenia/MCP-Odoo-Tools-CE-EE-and-online
/plugin install odoo-tools

Claude Code 不需要管理员权限：它的原生安装程序把它放在你的主文件夹中（在 macOS 和 Linux 上为 ~/.local/bin/claude），在 Windows 上，Anthropic 的指南说明无需以管理员身份运行它。在 Team 或 Enterprise 计划中，由你的组织决定你能获得哪些插件，以及 Claude Desktop 的 Code 标签页是否提供本地会话。

Claude 插件目录只在 Anthropic 审核之后才发布一个版本，因此它提供的 odoo-tools 可能比 Transgenia 的 marketplace 更旧（例如 1.4.0，早于 1.5.0 的权限策略），而且在此之前，在 Claude 应用中检查更新找不到更新的版本。在 Cowork 和 Claude chat 中，任何版本都不会运行 Odoo 工具，因此更新在那里不会改变这一点。只安装一个副本：引导路线会检查这一点（参见 两个 odoo-tools 副本）。

启用插件时，Claude Code 会提示你输入连接信息。之后如需修改：/plugin → odoo-tools → Configure options，或在会话中运行 /plugin configure <id>（在 VS Code 中，点击插件所在行的齿轮图标）。选项对话框不会说明它编辑的是插件的哪个副本。

插件选项只存在于 Claude Code 中

Cowork 不会提示输入插件选项，并且由于本插件的连接选项没有默认值，它会忽略本插件的 MCP 服务器；Claude chat 则会忽略插件的本地 MCP 服务器。因此这两者中都无法使用 Odoo 工具（skills 和命令仍会加载）。对于本插件的服务器，Claude Desktop 用状态 not_started 和原因 user_config_unsupported 来称呼这种情况；插件的任何更新都不会改变它。Claude Code 的云端会话是另一种情况：它有同步过来的插件，但没有插件的选项，这些选项留在你填写它们的那台电脑上，因此请使用本地会话。在 claude.ai 网页版上，插件的三点菜单提供删除、用 Claude 编辑或复制等操作，但没有填写连接选项的地方。参见 适用环境 和 故障排查。

无交互对话框（claude plugin configure）

在脚本中，或在远程或无界面的电脑上（Claude Code 2.1.285 或更高版本）：

  • claude plugin configure <id> --json 列出尚未保存值的选项。在一个正常工作的配置中，你未使用的那项凭据（API key 或密码）以及有默认值的选项仍会出现在该列表中；只有 odoo_url、odoo_db、odoo_login 和一项凭据必须有值。
  • claude plugin configure <id> --values-stdin 保存从标准输入读取的值，格式为一个由单行字符串组成的 JSON 对象。之后请重启 Claude Code。

<id> 是 claude plugin list 显示的完整标识符 名称@marketplace（例如从你的 Claude 账户同步的插件为 odoo-tools@synced）。请从受保护的文件或你的密钥管理器传入 JSON；切勿在命令行或聊天中输入 key。

插件的 mcpServers 条目通过以下命令启动服务器：

python3 ${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py

run_stdio.py 会把随附在 server/src 中的源代码放在 sys.path 的最前面（这样你机器上安装的其他 odoo_mcp 包都无法替代它），然后启动 stdio MCP 服务器。服务器 只使用 Python 标准库（MCP 协议以及 JSON-2、JSON-RPC 和 XML-RPC 传输都基于它实现），因此启动时 不安装、不下载任何东西：实际运行的代码就是插件文件夹中随附的、可直接阅读的代码。不需要在 PyPI 上发布，也不需要 uv 或虚拟环境。

插件选项

选项 是否必需 说明
Odoo URL 是 协议 + 主机，例如 https://my-company.odoo.com（不带结尾路径）
Odoo database 是 数据库名称
Odoo login 是 Odoo 用户的登录名（通常是邮箱）；建议使用最小权限用户
Odoo API key 是* Odoo ≥ 14：Preferences → Account Security → New API Key。Odoo 19+ 需要它来使用 JSON-2，这是 Odoo 22 中唯一保留的 API。sensitive 选项
Odoo password (Odoo < 14 only) 是* 仅限 Odoo 10-13（无 API keys）。sensitive 选项
Transport preference 否 auto（默认）/ json2 / jsonrpc / xmlrpc。在配置了 API key 的 Odoo saas~18.4 / 19.0+ 上，auto 使用 JSON-2，其他情况下先用 JSON-RPC，再用 XML-RPC
Request timeout 否 数字，每次 Odoo 调用的最长等待秒数（默认：120，即 Odoo 默认的 limit_time_real；最小 5，最大 3600）；对应 ODOO_TIMEOUT
Read-only mode 否 布尔值（默认：关闭）；写入、删除、导入和 Studio 工具不会被列出，调用其中一个会在任何内容到达 Odoo 之前被拒绝（对应 ODOO_READONLY）
Permission profile 否 standard（默认）、readonly、builder 或 full：在 Odoo 用户的权限之上，Odoo 工具可以做什么。full 保留 1.4 的行为。参见 权限策略（对应 ODOO_POLICY）
Permission policy file 否 为空（默认），或一个 JSON 文件的绝对路径，在配置档之上按模型定义规则，例如 ~/.config/odoo-tools/policy.json。请把它放在你的项目之外。服务器启动时读取一次（对应 ODOO_POLICY_FILE）

* 两者填写 其一：API key（Odoo ≥ 14）或密码（Odoo < 14）。

插件的 mcpServers 条目还把 ODOO_AUDIT_DIR 设为 ${CLAUDE_PLUGIN_DATA}/audit，把 ODOO_AUDIT_RETENTION_DAYS 设为 90：服务器为每次工具调用写一行审计记录，其中只有名称和计数，从不包含值或密钥（参见 审计日志）。自 v1.5.1 起，它还把 ODOO_DIAG_DIR 设为 ${CLAUDE_PLUGIN_DATA}/diagnostics：服务器的本地诊断，只含元数据（参见 本地存储）。

默认配置档是 standard

在 standard 下，odoo_unlink、odoo_add_field 和 odoo_add_automation 不会被列出，而且除其他外，外发邮件（内部备注除外）以及对用户、权限、模块和设置的更改都会被拒绝。如果你的流程需要 Odoo 用户允许的一切，请选择 full；如需在沙箱中处理字段、视图和自动化，请选择 builder。更改配置档后需要重新连接服务器（/mcp）。

sensitive 选项（API key 和密码）以掩码方式输入，并存储在 操作系统的安全凭据存储 中，绝不会写入 settings.json 或你的 shell 配置文件。对于插件，你 不需要（也不应该）在 ~/.bashrc、~/.zshrc 中或通过 setx 导出 ODOO_*。

两个 odoo-tools 副本

Claude Code 可以同时运行两个同名副本，例如一个来自 Claude 插件目录、装在某个项目文件夹中，另一个来自 Transgenia 的 marketplace、装在你的用户范围内。这时你保存的选项可能进入一个副本，而作出响应的却是另一个副本的工具。迹象如下：

  • Configure options 中没有 Permission profile（早于 1.5.0 的副本）；
  • odoo_version 的响应中没有 policy 块；
  • 插件的 Errors 标签页对一个你从未配置过的副本显示 Plugin option "odoo_url" isn't set。这条消息来自 Claude Code：它点名的副本（claude plugin list 中可以看到）没有保存任何选项。

自 v1.6.0 起，odoo_version 会点名作出响应的副本（plugin.copy，参见 验证），引导路线遇到早于 1.5.0 的副本时会在任何写入之前停止。

副本检查与选项检查

在 Claude Code 中，引导路线（/odoo-tools:odoo-setup-mcp）和 /odoo-tools:odoo-doctor 会运行副本检查，并对它保留的那个副本运行选项检查。下面就是这些 shell 命令，Claude 会在 Claude Code 中替你运行：

claude plugin list --json | python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-copies
claude plugin configure <id> --json | python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-options

${CLAUDE_PLUGIN_ROOT} 是插件文件夹，<id> 是要保留的副本，例如 odoo-tools@transgenia-odoo-tools。每项检查都从标准输入读取一条 Claude Code 命令打印的 JSON：它不运行任何程序、不联系任何地方，并且无论输入中有什么，都从不打印敏感值。两项检查都读取 UTF-8，从 Windows 的管道中读取时也是如此。没有需要修正的内容时以 0 退出，有需要修正的内容时以 1 退出，输入不是那种 JSON 时以 2 退出；--json 以 JSON 输出报告。选项检查需要 Claude Code 2.1.285 或更高版本。如果找不到 claude，它的完整路径是 "$HOME/.local/bin/claude"。

下面是项目文件夹中有一个来自插件目录的旧副本、同时有一个来自 Transgenia marketplace 的最新副本时，副本检查的输出：

odoo-tools copies Claude Code knows in this folder:
  active       odoo-tools@anthropic-plugin-directory 1.4.0 (project, ~/projects/odoo)
  active       odoo-tools@transgenia-odoo-tools 1.6.0 (user)
  not loaded   odoo-tools@synced unknown (synced from claude.ai): a copy on this computer has the same name and takes precedence
To fix:
  - 2 copies are active at once, so Claude Code may use the tools of one and the options of another. Keep one: odoo-tools@transgenia-odoo-tools 1.6.0 (user).
  - odoo-tools@anthropic-plugin-directory 1.4.0 (project, ~/projects/odoo) is older than 1.5.0: it has no permission policy, profile or audit log.
In a terminal (PowerShell, Terminal or bash), not inside Claude Code:
  cd ~/projects/odoo
  claude plugin uninstall odoo-tools@anthropic-plugin-directory --scope project
Then restart Claude Code, or run /reload-plugins inside it.
Result: 2 to fix

如何阅读：

  • 每个副本都带有它的状态、id、版本和范围：active（在此文件夹中已加载）、not loaded（一个来自 claude.ai 的副本，被本机上一个同名且优先的副本挡住）、other folder（另一个文件夹的安装，附有说明 installed for that folder only）或 disabled。同一个插件 id 安装在两个范围中只算一个副本；项目或本地安装只在它自己的文件夹中才算数：它的项目文件夹，或其中的某个文件夹。
  • To fix 说明要修正什么：同时有两个副本处于活动状态，或有一个早于 1.5.0 的副本，它没有权限策略、配置档或审计日志。它会点名要保留的副本，并按以下顺序优先：带权限策略的副本、来自 Transgenia marketplace 的副本、最新的副本、你用户范围内的副本。
  • In a terminal 给出移除其他副本的确切命令：先 cd 到项目文件夹（bash 或 PowerShell 需要时会加上引号，Windows 路径用 / 书写），然后运行 claude plugin uninstall <id> --scope <范围>（对于你用户范围内的副本，只有 --scope user，没有 cd）。如果文件夹名称中含有 "、$、`、!、[ 或 ]（它们是 PowerShell 的 cd 的通配符），或者它是网络路径（带有 \），cd 的位置会换成一行注释 # first change to this folder by hand: ...：请你自己切换到那个文件夹。请在 PowerShell、Terminal 或 bash 中运行它们，绝不要当作 /plugin 命令运行，然后重启 Claude Code，或在其中运行 /reload-plugins。
  • 在 claude.ai 上管理的副本无法从终端移除：Note: 这一行会让你在那里移除它（Customize, Plugins）。如果所有活动副本都早于 1.5.0，它还会给出留下一个最新副本的命令。对于来自 Transgenia marketplace 的旧副本，命令是 claude plugin marketplace update transgenia-odoo-tools，然后是 claude plugin update odoo-tools@transgenia-odoo-tools --scope <范围>；如果是项目或本地副本，前面先 cd 到项目文件夹。卸载后重新安装可能会复用本地一份过时的 marketplace 副本，装回同一个旧版本。更新命令始终有效。对于来自其他 marketplace 的副本，则是移除它的命令，然后是安装 Transgenia marketplace 副本的命令。如果没有任何活动副本，它会给出安装副本的命令。在安装之前，如果 Transgenia 的 marketplace 已经是已知的，它会先更新这个 marketplace。
  • Result: ok，或者还有多少项需要修正。

选项检查会列出 Odoo URL、数据库、登录名、设置了哪种凭据（API key、password 或 none，从不显示它的值）、Read-only mode，以及在带有权限策略的副本上的配置档和策略文件。对于 URL，它只显示协议、主机和端口：从不复述用户信息、路径、查询或片段，因为它们可能带有密码，或者复制来的门户链接中的令牌。如果 URL 中带有 @，或者无法读出主机，它只说明 URL 已设置，而不显示它的任何部分：密码中的 # 或 ? 会改变 URL 被切分的位置。在 To fix 下，它会标出没有 Permission profile 选项的副本（早于 1.5.0：请运行副本检查）、缺少的必需选项、缺少的凭据、带有任何 @ 的 URL（视为带有用户名或密码而拒绝），以及不只是协议加主机的 URL。在 Note: 下，它会提醒同时设置了 API key 和密码（使用 API key）、URL 结尾的 /（会被忽略）、通往另一台电脑的未加密 http，以及短于 30 秒的请求超时。缺少的选项请在 Claude Code 中用 /plugin configure <id> 打开的对话框里填写，绝不要在聊天中填写。

在终端中移除副本

不借助 Claude 时，在终端中、从项目文件夹运行 claude plugin list，它会显示每个副本及其版本和范围；保留一个 odoo-tools@...，并在那里移除其他副本：

claude plugin list
claude plugin uninstall odoo-tools@anthropic-plugin-directory --scope project

请使用 claude plugin list 显示的 id 和范围（为你的用户安装的副本用 --scope user），然后重启 Claude Code。插件目录的副本是 odoo-tools@anthropic-plugin-directory；不存在 odoo-tools@claude-plugins-official。

如果你保留的副本是来自 Transgenia marketplace 的旧副本（早于 1.5.0），不要先卸载再重新安装：安装可能会复用本地一份过时的 marketplace 副本，装回同一个旧版本。更新命令始终有效：请先更新 marketplace，再更新这个副本，并使用 claude plugin list 显示的范围（对于项目或本地副本，请在项目文件夹中运行）：

claude plugin marketplace update transgenia-odoo-tools
claude plugin update odoo-tools@transgenia-odoo-tools --scope user

直接运行 MCP 服务器（独立模式）

# 在 checkout 中，使用 python3 3.9+（无需安装任何东西）
python3 server/run_stdio.py

# 或作为软件包安装（建议使用虚拟环境）；提供 odoo-mcp 命令
pip install ./server && odoo-mcp

要求

  • MCP 服务器： PATH 中有 python3 3.9 或更高版本。仅此而已：运行时零第三方依赖。可用 python3 --version 检查。
    • macOS： python3 随 Apple 的 Command Line Tools 一起提供（xcode-select --install）。如果你的 Mac 在安装它们时要求管理员，而你不是管理员，由你的 IT 团队来安装，或请 Transgenia 提供协助配置。
    • Linux： 各发行版都自带 python3（如果缺失，请用包管理器安装，例如 sudo apt install python3）。
    • Windows： 命令必须名为 python3。Microsoft Store 版 Python 提供 python3.exe；python.org 安装程序只会创建 python.exe/py.exe：请安装 Microsoft Store 版 Python，或在 PATH 中放一个 python3.exe（在同一文件夹中放一个 python.exe 的副本或硬链接；PowerShell 命令见下文）。PowerShell 或 doskey 别名 不够用，因为 Claude Code 会直接启动该命令。没有 python3 时，claude mcp list 会把插件的服务器报告为 Failed to connect 并带有 Connection closed，而且没有任何地方提到 Python。参见 故障排查。
    • Windows，会话开始的 hooks： 它们是 shell 命令，因此需要 Git for Windows（Git Bash）。没有它时，Claude Code 会在 PowerShell 中运行它们，并以 SessionStart hook 错误失败。如果已安装 Git Bash 但 Claude Code 找不到它，请设置 CLAUDE_CODE_GIT_BASH_PATH。MCP 服务器不受影响。
    • Windows，安装 Claude Code、Git 或 Python 之后： 打开一个新的 PowerShell 窗口并重启 Claude Code；安装之前打开的窗口看不到新的 PATH（无法识别 claude，或 where.exe git 什么也找不到）。Claude Code 的原生安装程序把 claude.exe 放在 %USERPROFILE%\.local\bin 中。
  • 备用 CLI（可选）： Node.js 18+。

Windows：在 python.exe 旁边放一个 python3.exe

在 PowerShell 中创建硬链接：

$python = (Get-Command python -ErrorAction Stop).Source
New-Item -ItemType HardLink -Path (Join-Path (Split-Path $python) "python3.exe") -Target $python

它需要对 Python 文件夹的写入权限：对于安装在 C:\Program Files 下的 Python，请以管理员身份运行 PowerShell。如果 Get-Command python 什么也找不到，或找到的是 WindowsApps 下的文件，说明 Python 不在 PATH 中：请重新运行 python.org 安装程序并勾选 "Add python.exe to PATH"，或安装 Microsoft Store 版 Python。CI 会在 Windows 上检查这个修正方法（windows-launch.yml）。

可选附加项

pip install -e "./server[cache]"    # 带 TTL 的模式缓存（cachetools）
pip install -e "./server[metrics]"  # /metrics 上的 Prometheus 指标
pip install -e "./server[otel]"     # OpenTelemetry 追踪（OTLP）

附加项永远不会阻塞启动：如果未安装，这些能力只会保持未激活状态（优雅降级；此时模式缓存使用基于标准库的实现）。插件 不会安装任何附加项。

独立模式配置（环境变量）

仅当你在 插件之外 运行服务器时适用（Docker、python -m odoo_mcp、在 checkout 中运行 python3 server/run_stdio.py）。在插件内部，这些值由插件选项填充。

变量 是否必需 说明
ODOO_URL 是 https://host（不带结尾路径）
ODOO_DB 是 数据库名称
ODOO_LOGIN 是 登录邮箱
ODOO_API_KEY 是* Odoo ≥ 14；在 Account Security 中创建。这是 JSON-2 唯一接受的凭据
ODOO_PASSWORD 是* 在 Odoo < 14 中使用（无 API keys）
ODOO_TRANSPORT_PREF 否 auto（默认）/ json2 / jsonrpc / xmlrpc（参见 兼容性）
ODOO_READONLY 否 1 表示只列出并运行读取工具（选项 Read-only mode）
ODOO_POLICY 否 权限配置档：readonly、standard（默认）、builder 或 full（选项 Permission profile，参见 权限策略）
ODOO_POLICY_FILE 否 可选策略文件的绝对路径（选项 Permission policy file）
ODOO_AUDIT_DIR 否 审计文件夹；stderr（插件之外的默认值）或 off
ODOO_AUDIT_RETENTION_DAYS 否 审计文件的保留天数（默认 90；0 表示一直保留）
ODOO_DIAG_DIR 否 本地诊断的文件夹（server.jsonl，只含元数据）；不设置或设为 off 时不写入任何内容。插件传入的是 ${CLAUDE_PLUGIN_DATA}/diagnostics
ODOO_TIMEOUT, ODOO_CACHE_TTL 否 整数（秒）；ODOO_TIMEOUT（默认 120）适用于 JSON-RPC，自 v1.2.0 起也适用于 XML-RPC
ODOO_METRICS, ODOO_OTEL_ENDPOINT 否 可选的可观测性

* 你必须定义 ODOO_API_KEY 或 ODOO_PASSWORD 其中 一个。

MCP 服务器 不会将凭据持久化到磁盘；它的审计记录只保存名称、计数和耗时，本地诊断只保存元数据。Transgenia 不会接收你的凭据或数据；但工具结果会像任何工具一样返回给你的 MCP 客户端和模型提供方。参见 隐私。

在配置策略文件之前先检查它（离线进行，不会向 Odoo 发送任何内容）：

python3 server/run_stdio.py --check-policy ~/.config/odoo-tools/policy.json --explain res.users:write

参见 --check-policy。

支持报告同样离线生成：python3 server/run_stdio.py --diagnose 读取本地诊断（ODOO_DIAG_DIR）和审计日志（ODOO_AUDIT_DIR），或者你用 --diag-dir 和 --audit-dir 传入的文件夹，从不联系 Odoo。参见 支持。

备用 CLI（可选）

/odoo-tools:odoo-setup-cli

需要 Node.js 18+。它会将 CLI 安装到 ~/.claude/tools/odoo-cli，并在其中创建一个仅你的用户可读、带占位符的本地 .env：由你自己在自己的编辑器中粘贴密钥（API key 或密码）；Claude 绝不会在聊天中向你索取它。命令详情见 备用 CLI 页面。

Docker（可选）

仓库的 docker/ 目录用于构建一个运行同一 stdio 服务器的镜像。使用 docker run -i --rm --env-file ./odoo.env odoo-mcp-tools 连接，其中 odoo.env 是你自行创建、包含 ODOO_* 变量的文件（权限 600，不纳入版本控制）。该文件还可以设置权限策略和审计文件夹；请以只读方式挂载策略文件，并以容器用户（mcp）可写的方式挂载审计文件夹：

# 在 odoo.env 中
# ODOO_POLICY=standard
# ODOO_POLICY_FILE=/policy/policy.json
# ODOO_AUDIT_DIR=/audit

docker run -i --rm --env-file ./odoo.env \
  -v ~/.config/odoo-tools/policy.json:/policy/policy.json:ro \
  -v ~/.odoo-tools/audit:/audit ghcr.io/transgenia/odoo-mcp-tools:1.6.0

没有审计文件夹时，日志行会写到 docker logs。自 v1.5.0 起，服务器从不从客户端请求中获取 Odoo 的 URL 或密钥：基于请求头（X-Odoo-Url/Db/Login + Bearer）的多租户路径已被移除，ODOO_MULTITENANT 仍会被读取，但保留不用、没有任何效果。自 v1.5.1 起，服务器不再读取任何其他凭据：它过去读取但从未使用的 ODOO_HTTP_BEARER 已不再被读取。没有 ODOO_DIAG_DIR 时，容器不会写入本地诊断。由服务器保管 Odoo 凭据、客户端向服务器认证的远程 HTTP 模式已列入路线图，需要单独设计。

验证

调用 odoo_version 工具（或运行 /odoo-tools:odoo-doctor）。一个成功的、报告了版本、版本类型、部署方式和传输方式的响应，即可确认端到端的安装（自 v1.4.0 起，odoo_version 会先登录，因此错误的凭据不会再被当作连接正常）。参见 连接与发现。

如果会话开始时你看到一条以 odoo-tools: In Cowork and Claude chat this plugin's Odoo tools do not run 开头的提示，说明本地诊断在最近 14 天既没有记录到与 Odoo 的成功连接，也没有记录到带齐全部连接设置的服务器启动。在 Claude Code 中，请在 Configure options 中填写选项并重启；在 Cowork 或 Claude chat 中，请打开 Claude Desktop 的 Code 标签页中的本地会话。参见 故障排查。

自 v1.5.0 起，odoo_version 的响应包含一个 policy 块，其中有当前生效的配置档、摘要（digest）和被隐藏的工具。如果会话开始时插件提示权限策略在上一次服务器启动时锁定了工具（the permission policy locked the Odoo tools），请让 Claude 调用 odoo_version 查看原因，修正该选项或文件，然后用 /mcp 重新连接服务器。参见 故障排查。

自 v1.6.0 起，响应中还带有一个 plugin 块：作出响应的 odoo-tools 版本，以及在 Claude Code 中它的已安装副本（plugin@marketplace，例如 odoo-tools@transgenia-odoo-tools），策略被锁定时也有。没有 policy 块的响应来自早于 1.5.0 的副本：引导路线和 /odoo-tools:odoo-doctor 会在那里停止。参见 两个 odoo-tools 副本。