多少企业已经听说"AI可以与ERP对话"，却没人解释：Odoo在第12版到第19版之间重命名了数十个模型，如果MCP服务器不能在运行时处理这一问题，智能体就会悄然出错。本文介绍我们构建的解决方案：它是什么、为何选择MIT开源、以及哪些功能是有意保留在私有层的。
account.invoice → account.move）。该插件以Claude Code插件形式分发，通过 uvx 安装，源代码在GitHub上以MIT许可公开发布。
真正的问题：Odoo模型名称在各版本间不断变化
Odoo是拉丁美洲中小企业中应用最广泛的ERP，但它有一个顾问在签合同前几乎不会提及的特点：每个主要版本都会重组或重命名模型和字段。最广为人知的例子是 account.invoice，在Odoo 13中更名为 account.move。第10版至第19版之间还有数十处类似变更。
对于了解历史的人类来说，这是一条学习曲线。对于AI智能体而言，这是一个静默失败点：智能体满怀信心地调用旧模型名称，ERP返回一个看似权限问题或网络问题的错误，智能体无法区分这究竟是凭证问题还是命名问题。
我们本可以构建一个假定Odoo 19的MCP服务器一了百了。但这会将数千家运行着功能完好的14、16或17版本的企业排除在外，它们没有任何理由仅仅因为AI的到来就去迁移。
MCP-Odoo-Tools是什么
MCP-Odoo-Tools是一个Python服务器，在Odoo之上实现了模型上下文协议（MCP，由Anthropic作为开放标准发布）。源代码以MIT许可在GitHub上公开发布，是全新的干净实现，不派生自任何AGPL分支，并以Claude Code插件形式打包分发。
使它区别于基础Odoo集成的特点：
跨版本兼容层。 一个声明式映射表涵盖了Odoo 10至19版本间模型和字段名称的差异。当智能体请求发票数据时，兼容层在运行时确定已连接的实例使用 account.invoice 还是 account.move，智能体和运营人员都无需提前了解版本信息。
版本和版次自动检测。 服务器在连接时识别Odoo的精确版本（社区版/企业版/在线版）、版次和部署模式，该信息反馈给兼容层和传输协议选择器。
双传输协议与自动回退。 服务器以XML-RPC为主要协议，以JSON-RPC为备选。回退机制至关重要：从Odoo 17开始，/jsonrpc 端点需要特定的API Key，服务器会自动检测版本并透明地选择正确的传输协议。
可选模式缓存。 对 odoo_fields_get 的重复调用从内存中获取（可配置TTL缓存），降低密集工作会话中的延迟。
内置可观测性（可选）。 每次RPC调用生成带有 odoo.model、odoo.method 和 odoo.alias 属性的OpenTelemetry span。若未配置OTLP端点，服务器正常启动而不发送追踪数据，优雅降级，零错误。
可用工具
服务器按操作领域提供18个工具：
| 类别 | 工具 | 功能 |
|---|---|---|
| 读取 | odoo_search_read | 使用ORM过滤器搜索并返回记录 |
| 读取 | odoo_fields_get | 描述模型字段（支持可选缓存） |
| 读取 | odoo_search_count | 统计记录数量而不获取数据 |
| 导出 | odoo_export_records_json | 通过ORM导出记录，遵守权限设置 |
| 导出 | odoo_export_records_csv | 以CSV格式导出 |
| 写入 | odoo_create / odoo_write | 创建或更新记录 |
| 写入 | odoo_unlink | 删除记录 |
| 写入 | odoo_execute | 调用任意模型方法 |
| 消息 | odoo_message_post | 在记录的讨论区发布消息 |
| 元数据 | odoo_version | 返回实例的版本和版次 |
| 元数据 | odoo_list_models | 列出已安装的模型 |
| 会话 | user_connection_activate | 在会话开始时激活连接 |
完整的18个工具涵盖读取、写入、导出和元数据查询场景，完整参考文档请见代码仓库。
作为Claude Code插件安装
该插件附带用于通过 uvx 安装的 plugin.json 以及用于自托管的 marketplace.json。安装后，odoo-setup-mcp 技能将引导初始配置：实例URL、凭证和自动版本检测。
插件还包括：
- 技能：
odoo-setup-mcp、odoo-setup-cli、odoo-connect、odoo-crossversion。 - 专用智能体：
odoo（通用操作）和odoo-migrator（跨版本迁移任务）。 - CLI备用方案：基于XML-RPC的TypeScript实现，适用于MCP服务器不可用的环境。
关于应用市场的说明：该插件以自托管安装形式分发，尚未在Anthropic官方应用市场发布，它是来自Transgenia自有仓库的开源插件，在官方应用市场发布的流程正在评估中。
公开层有意排除的内容
公开版本包含通用核心。以下内容是有意保留在私有层的：
- 墨西哥财税层（CFDI/SAT）：UUID验证、CFDI凭证库读取、
l10n_mx_edi_cfdi_sat_state查询。该层在有监督的实施项目中提供。 - VoBo中间件（Visto Bueno，审批关卡）：写操作治理，在创建或修改生产记录前需要明确的人工授权，提供可配置的强制执行选项。
- S3备份工具：实例备份和恢复。
- 视觉与发票解析工具：使用语言视觉能力读取文档和PDF。
这些层只有在有监督的实施环境中才有意义。公开核心本身已完全可用，这些不是为了推动升级而削减的功能，而是需要团队入职流程的功能模块。
如需了解插件之前的基础API Key层，通过API Key将Odoo连接到Claude并无需Python创建自定义视图介绍了基础选项及其实际局限性。
为何选择开源，为何选择MIT
有一个务实的理由：封闭的MCP服务器会造成供应商依赖。如果定价改变、商业模式转变或公司消失，AI智能体就会停止工作。有了开源（MIT），企业拥有代码，可以自行托管，可以聘请任何服务商维护。即使Transgenia明天不复存在，该插件仍然可以正常运行。
还有生态系统方面的考量：越多企业为Odoo MCP服务器做出贡献，它对所有人就越健壮。兼容层今天覆盖Odoo 10-19；社区可以在不依赖任何特定供应商的情况下将其扩展到未来版本。
我们选择MIT而非AGPL，是为了让企业无需担心著佐权限制就能将插件集成到其专有技术栈中。著佐权有其适用场景；这里我们优先考虑推广采用。
已验证的技术质量
插件附带完整的CI体系：
- 27个单元测试全部通过：覆盖版本兼容表、传输回退回归测试和缓存测试。
- 代码检查：ruff在Python 3.11和3.12上均无报错。
- TypeScript CLI：编译无错误。
- 真实MCP握手（stdio）：正确列出全部18个工具。
- 实时版本矩阵（可选）：针对临时搭建的Odoo 16、17、18实例。
如何开始
如果您有Odoo实例并希望探索AI智能体集成，推荐的路径分三步：
- 实例诊断：版本、版次、已安装模块以及适合AI自动化的业务流程。
- 只读试点：在只读模式下连接智能体，验证响应的正确性，然后再操作生产数据。
- 写操作前先建立治理：VoBo中间件作为可选层已经存在，启用它只需更改配置，无需重写代码。
如果您希望在决策前先看到实际运行效果，我们的分行业演示展示了智能体使用相同MCP协议处理诊所和批发分销商数据的场景。
→ 查看演示 →
常见问题
MCP-Odoo-Tools是免费的吗？
是的。公开层采用MIT许可，不收取费用。您可以从GitHub仓库自行安装和配置。墨西哥财税层（CFDI/SAT）、写操作治理中间件（VoBo）及其他高级组件可在Transgenia的有监督实施方案中获取。
支持哪些Odoo版本？
支持Odoo社区版、企业版及在线版（SaaS），版本从10到19。兼容层自动解析各版本间模型和字段名称的差异，包括v13中的 account.invoice → account.move 等重命名，以及后续版本中的其他变更。
仅支持Claude，还是支持其他AI智能体？
支持任何实现了模型上下文协议（MCP）的智能体。MCP是Anthropic作为开放规范发布的标准。Claude Code是该插件针对的参考环境，但服务器提供兼容其他MCP客户端的标准接口。
插件会将我公司的数据发送到Transgenia的服务器吗？
不会。MCP服务器运行在您的基础设施中，直接与您的Odoo实例通信。数据不会经过Transgenia的任何服务器。该插件仅仅是您运行的代码：您的数据始终在您的安全边界内。
它是Anthropic认可的官方插件吗？
目前还不是。该插件是开源的，从Transgenia自有仓库分发。Transgenia是Anthropic Claude合作伙伴网络的注册合作伙伴，这意味着Anthropic认可我们作为合作伙伴，而不是说该插件经过他们的认证或审计。这个区别很重要：代码是开放的，任何人都可以审查。
关于作者和Transgenia
Efraín Carreón Ortiz是墨西哥科技精品公司 Centrum Transgenia 的首席执行官。他持有Anthropic颁发的官方 Claude Code 徽章（Claude合作伙伴徽章），可在 Credly 上验证。
Transgenia是 OpenAI合作伙伴网络 中的 OpenAI精选合作伙伴，同时也是Anthropic Claude合作伙伴网络的 注册合作伙伴。我们在自有生产环境中运营十二个受治理的AI智能体，并在医疗和B2B领域提供可验证的实施陪伴服务。
继续阅读
- 通过API Key将Odoo连接到Claude并无需Python创建自定义视图：插件之前的基础层，了解基础选项及其实际局限性。
- Transgenia如何使用受治理的AI智能体运营：围绕该插件在生产中运行的治理模型（草稿优先、人工VoBo、MCP）。
- 在企业中实施Claude：分阶段指南：来自Anthropic注册合作伙伴的完整采用方法。
- MCP-Odoo-Tools 使用手册：插件的完整参考，安装、18个工具和跨版本兼容性。
- 我们的受治理AI解决方案。