跳转至

Odoo Tools：简介

MCP-Odoo-Tools 是一个 Claude Code 插件，通过单次安装统一访问 Odoo：一个 MCP 服务器（主要接口）和一个 备用 CLI。它支持 Odoo Community、Enterprise 和 online (SaaS)，从 第 10 版到第 19 版，这得益于一个兼容层，它能自动解析在不同版本之间发生变化的模型名和字段名。它的 skills 和命令也会在 Cowork 和 Claude chat 中加载，但 Odoo 工具只在 Claude Code 中运行（参见 适用环境）。

Online/SaaS：需要支持外部 API 的订阅计划

只有启用了 API 访问的 Odoo Online 订阅（Custom 计划）才支持外部 RPC 访问。在没有外部 API 访问的计划上，即使凭据正确，连接也会失败：请用 odoo_version 验证，并在连接出错时查阅 故障排查与常见问题。在 Odoo Online 上，唯一可用的凭据是 API key。

从这里开始

安装插件后运行 /odoo-tools:odoo-setup-mcp：涵盖配置、培训、使用与部署的引导路线。没有可练习的 Odoo？/odoo-tools:deploy-local 会启动一个 本地沙箱。

v1.6.0 新增：只保留一个副本、保留正确的副本，每条命令放在正确的地方

  • 按环境区分的安装命令： 在 Claude Code 中用 /plugin install，在终端中用 claude plugin install ... --scope user。只安装一个副本。参见 安装。
  • odoo_version 会点名作出响应的副本（plugin 块），引导路线和 /odoo-tools:odoo-doctor 会发现第二个副本或早于 1.5.0 的副本，并在那里停止。参见 两个 odoo-tools 副本。
  • 没有 python3 的 Windows： claude mcp list 会把服务器报告为 Failed to connect 并带有 Connection closed，而且没有任何地方提到 Python。解决办法见 故障排查。
  • 应用的 not_started 状态： /odoo-tools:odoo-doctor 和引导路线会把状态 not_started、原因 user_config_unsupported 识别为 Cowork 和 Claude chat 的情况：它不是错误，任何更新都不会改变它。它们会引导你使用 Code 标签页中的本地会话或 Claude Code；Claude Code 不需要管理员权限。参见 故障排查。
  • 本地沙箱为插件提供 API key（Odoo 14.0 至 19.0）。参见 本地部署。
  • 仍然是 28 个工具。在 Odoo 10 至 12 上，策略还会拒绝按位置传递的对象中既不是模型字段、也不是允许的上下文键的键，因此策略的摘要会改变。参见 权限策略。

v1.5.1 新增：在每个环境中如实说明，并提供本地诊断

  • 先确认 Claude 在哪里运行。 当 Odoo 工具没有加载时，/odoo-tools:odoo-doctor 不运行任何命令、不检查 Python，也不给出 Odoo 方面的建议：在 Cowork 和 Claude chat 中，它会引导你去 Claude Desktop 的 Code 标签页或联系 Transgenia。使用 Odoo 工具的 skills、命令和智能体都会先做同样的检查。
  • 本地诊断与支持报告。 服务器会在你的电脑上保存一份只含元数据的小型记录，doctor 最后会给出一份不含 key、URL、登录名或记录数据的报告，你可以把它发给 Transgenia。参见 支持。
  • 一个不读取任何插件选项或凭据的会话开始 hook，服务器也不再读取 ODOO_HTTP_BEARER。参见 安全。
  • 仍然是 28 个工具。配置档 readonly、standard 和 builder 会多拒绝一些调用（上下文规则也适用于按位置传递的对象，Odoo 10 至 12 会把它当作上下文），因此策略的摘要会改变。参见 权限策略。

v1.5.0 新增：默认安全的权限

MCP 服务器在 Odoo 用户的权限之上应用一套 权限策略。默认配置档 standard 可以读取、创建、更新并运行业务方法，但不删除、不做 Studio 风格的改动、不发送邮件或短信（内部备注可以），也不读取已保存的密钥；它列出 28 个工具中的 25 个。每次调用都会在本地审计日志中留下一行。要保留 1.4 的行为，请把 Permission profile 选项设为 full。

它由 Transgenia 构建并维护，Transgenia 是 Anthropic 注册合作伙伴（Registered 层级）。这是一个独立的开源项目，采用 MIT 许可证，它不是 Anthropic 的认证产品或第一方产品。它已在 Anthropic 的插件目录中上架；每个新版本须经 Anthropic 审核员批准后才会进入目录，因此目录提供的版本可能早于本手册所述的版本。请只安装一个副本，并从 Transgenia 的 marketplace 安装（参见 安装）。

适用环境

环境 MCP 服务器（Odoo 工具） Skills 和命令 智能体和 hooks
你电脑上的 Claude Code（终端、VS Code、JetBrains、Claude Desktop 的 Code 标签页中的本地会话） 是 是 是
云端会话中的 Claude Code（Claude Desktop 的 Code 标签页、claude.ai/code） 否 是 是
Cowork（Claude Desktop） 否 是 是
Claude chat（claude.ai 网页版、桌面版、移动版） 否 是 否

Odoo 工具作为一个通过 stdio 运行的本地 MCP 服务器（python3 3.9+），运行在 Claude Code 所在的机器上；连接信息（URL、数据库、登录名、API key）在 Claude Code 的插件选项（plugin.json 中的 userConfig）中填写：启用插件时 Claude Code 会提示你输入，也可以通过 claude plugin configure 传入。

根据 Anthropic 的插件支持矩阵，Cowork 不会提示输入选项值，并会忽略引用了无默认值选项的 MCP 服务器（本插件的 URL、数据库、登录名和凭据都没有默认值）；Claude chat 则会忽略插件的本地 MCP 服务器。在这些应用中，插件可以安装，它的 skills 和命令也会加载，但没有这些工具就无法访问 Odoo。这是这些应用的设计行为，而不是安装损坏。

对于本插件的服务器，Claude Desktop 用状态 not_started 和原因 user_config_unsupported 来称呼这种情况：在 macOS 和 Windows 上都一样，它不是插件或应用的故障，插件的任何更新也都不会改变它。

你的账户、你的 Odoo 和你的 Python 都没有问题。请打开 Claude Desktop 的 Code 标签页中的本地会话（或在终端、VS Code 或 JetBrains 中使用 Claude Code）：你安装在 Claude 账户上的插件，会在你用同一账户登录后作为同步插件出现在那里。也可以请 Transgenia 提供协助配置：dev@transgenia.org · WhatsApp +52 55 8034 0405。

Claude Code 的云端会话（Code 标签页的云端环境，或 claude.ai/code）是另一种情况：插件会从你的账户同步过去，但它的选项不会。Claude Code 把选项保存在你填写它们的那台电脑上（API key 和密码保存在那台电脑的安全凭据存储中），因此服务器不会在云端启动。请使用本地会话。

Cowork 和 Claude chat 确实接受你自行添加的 MCP 连接器：一个可通过 https URL 访问的远程 MCP 服务器，或在桌面应用中的一个桌面扩展。本插件不提供其中任何一种：它的 Odoo 工具需要本地服务器。如果你在 claude.ai 上看到 odoo 一行带有 Runs in each session 字样且面板为空，请参见 故障排查与常见问题。

它解决什么问题

Odoo 的模型名和字段名 在不同版本之间会变化：

  • account.invoice 在 v13 中被合并进 account.move（是合并而非重命名：在 v10-v12 上它们作为发票与日记账分录并存；参见 兼容性）。
  • 分析字段在 v16 中发生了变化（analytic_account_id → analytic_distribution）。
  • 包裹模型在 v19 中发生了变化（stock.quant.package → stock.package）。
  • name_get 方法在 v18 中被移除（改为读取 display_name）。
  • Odoo Online 会在其 saas~N.M 版本线上提前引入变更：uom_po_id 自 saas~18.1 起就已不存在，早于 19.0。
  • RPC API 本身自 v19 起也在变化：/xmlrpc 和 /jsonrpc 被弃用，Odoo 22（以及 Odoo Online saas~21.1）将移除它们；替代方案是 JSON-2，当配置了 API key 时，服务器会自动使用它。

此外，Enterprise 包含 Community 所没有的模型。对于一个 AI 智能体而言，这些差异中的每一个都是一个静默的故障点：它调用了旧名称，ERP 返回错误，而智能体无法分辨这究竟是权限问题、网络问题还是版本问题。

本插件将这些差异吸收在 一个稳定的工具接口 之后，让你无需为每个版本分叉你的代码。

两个接口

接口 何时使用 要求
MCP 服务器（推荐） 从 Claude Code 的常规使用：28 个工具（包括 6 个面向 Odoo Online 的工具；默认配置档 standard 下列出 25 个）+ 完整兼容层，通过 JSON-2、JSON-RPC 或 XML-RPC，并带有 权限策略 和审计日志 python3 3.9+（仅标准库；不安装任何东西）
备用 CLI 当你无法运行 MCP 服务器时，或用于脚本的批量访问 Node.js 18+

范围（公开 vs. 私有）

这是 公开的通用核心：只与 Odoo 通信，别无其他。自 v1.5.0 起，一套通用的、声明式的权限策略属于公开核心的一部分。审批流程、本地化引擎（例如各国的电子发票）、备份、文档 AI 以及其他客户专属引擎都被 有意排除在本仓库之外，作为 Transgenia 受监督实施的一部分提供。

下一步

继续阅读 安装，或直接跳到有引导的 快速开始。

实施支持

需要帮助把它连接到你的 Odoo，或需要一个定制的 AI/ERP 集成？Transgenia 提供 AI 与 Odoo 的实施服务。欢迎写信给我们：dev@transgenia.org。