Odoo

Odoo MCP 服务

一个 MCP 服务，可让 AI 助手（Claude Desktop、Claude Code 或任何 MCP 客户端）读取你的 Odoo 销售、采购、制造和库存数据；仅当你启用后，才能更新采购订单行的承诺日期。

• 12 个读取工具和 1 个写入工具（如下所列）。
• 默认只读。 服务端需要设置 ODOO_MCP_ENABLE_WRITES=true，且每次调用都必须提供准确的确认文本，才能使用写入工具。
• 作为你配置的用户，通过 Odoo 外部 JSON-RPC API（/jsonrpc）进行通信。适用 Odoo 的访问权限。
• 在本地通过 stdio 运行。没有遥测；仅连接到你的 Odoo。

由 Helios One 构建。MIT 许可证。

快速开始（2 分钟）

你需要 Node.js 20 或更高版本，以及一个能够登录外部 API 的 Odoo 用户。

1. 在 Odoo 中获取 API 密钥（推荐使用 API 密钥，而非密码）：点击你的头像，然后选择 我的个人资料 / 偏好设置，打开 账户安全，点击 新建 API 密钥。复制密钥。

2. 将服务添加到 MCP 客户端。

Claude Code：

claude mcp add odoo \
  -e ODOO_URL=https://odoo.example.com \
  -e ODOO_DB=mydb \
  -e [email protected] \
  -e ODOO_API_KEY=your-api-key \
  -- npx -y @heliosone/odoo-mcp

Claude Desktop：打开 设置 > 开发者 > 编辑配置，将以下内容添加到 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "odoo": {
      "command": "npx",
      "args": ["-y", "@heliosone/odoo-mcp"],
      "env": {
        "ODOO_URL": "https://odoo.example.com",
        "ODOO_DB": "mydb",
        "ODOO_USERNAME": "[email protected]",
        "ODOO_API_KEY": "your-api-key"
      }
    }
  }
}

3. 提问，例如：“哪些采购订单行已逾期，逾期了多少天？” 或 “S00042 的状态是什么？”

设置

变量	必需	含义
ODOO_URL	是	你的 Odoo 基础 URL，例如 https://odoo.example.com
ODOO_DB	是	数据库名称
ODOO_USERNAME	是	用户登录名
ODOO_API_KEY	二选一	该用户的 API 密钥（代替密码使用）
ODOO_PASSWORD		用户密码
ODOO_MCP_ENABLE_WRITES	否	true 允许使用写入工具。其他值都会使服务保持只读。
ODOO_TIMEOUT_MS	否	请求超时时间，默认 30000

即使缺少设置，服务也会启动，因此客户端可以列出工具。之后每次调用都会返回 CONFIGURATION_ERROR，并列出缺少的设置项名称。

工具

工具	返回内容
list_open_sales_orders	已确认但尚未全部交付的销售订单（includeQuotations 可包含报价单）
list_open_purchase_orders	已确认但尚未全部收货的采购订单（includeRfqs 可包含询价单）
get_order_status	一张销售或采购订单及其行项目（订购量 / 已交付或已收货 / 已开票）和相关调拨单。可按 ID、编号或客户 / 供应商参考信息查询。
list_supplier_promise_dates	已确认采购订单中的未结行项目，包含供应商预计到货日期，并按日期从早到晚排序
list_late_purchase_lines	已超过预计到货日期且尚未全部收货的采购订单行，包含 days_late
list_late_sales_lines	已超过承诺日期且尚未全部交付的销售订单行，包含 days_late。承诺日期 = 订单承诺日期；若无，则为订单日期 + 行项目提前期。
list_manufacturing_orders	制造订单，包含状态、数量、计划日期和组件可用情况
list_work_orders	工单：工序、工作中心、状态、预计时长和实际时长
list_shipments	收货、交付或内部调拨；lateOnly 可筛选出已超过计划日期的记录
lookup_customer	按名称、电子邮件、参考信息或 VAT 查找联系人，优先显示客户
lookup_supplier	按名称、电子邮件、参考信息或 VAT 查找联系人，优先显示供应商
get_inventory_on_hand	产品数量：现有量、预测量、入库量、出库量
update_po_line_promise_date	写入。 设置一个采购订单行的预计到货日期。参见下文。

列表工具接受 limit（默认 50，最大 500）和 offset。结果包含 Odoo 自带的字段值，以及少数计算字段（qty_open、days_late、promised_date）。你的 Odoo 版本中不存在的字段将被省略。

写入工具

update_po_line_promise_date 会修改一条采购订单行的 date_planned（例如供应商确认了新的日期后）。只有同时满足以下两项时才会运行：

1. 启动服务时设置了 ODOO_MCP_ENABLE_WRITES=true，并且
2. 调用中包含 "confirmation": "CONFIRM update_po_line_promise_date"。

否则，它会返回 WRITES_DISABLED 或 CONFIRMATION_REQUIRED，并且不会调用 Odoo。未指定时间的日期会按 12:00 UTC 存储，因此在大多数时区中显示为同一天。结果会显示修改前后的值。

测试情况

于 2026 年 10 月 24 日进行了测试：将打包后的 npm tarball 安装到空项目中，通过官方 MCP TypeScript SDK 客户端经由 stdio 驱动其 odoo-mcp 命令，并使用全新的可自托管 Odoo Community 17.0、18.0 和 19.0 进行测试（从官方 odoo/odoo 分支构建；已安装 Sales、Purchase、Inventory 和 Manufacturing；使用虚构记录）。每个版本均通过以下测试：

• 列出了全部 13 个工具，所有 12 个读取工具均返回了预置记录（每个版本进行了 21 次工具调用和 25 项检查，全部通过）；
• 写入功能关闭时，写入工具被拒绝（WRITES_DISABLED）；未提供确认文本时也被拒绝（CONFIRMATION_REQUIRED）；之后写入成功，直接读取 Odoo 确认了新日期；
• 服务使用 Odoo API 密钥登录；其中一个会话改用普通密码，错误密码则返回 AUTH_FAILED；
• 另有一次调用通过 MCP Inspector CLI 执行。

日志：proof/。单元测试（npm test，使用内存中的 Odoo 模拟对象）在 Node.js 20 和 25 上均通过。

未测试： Odoo Online（odoo.com 托管）和 Odoo.sh、Odoo Enterprise、17 之前的 Odoo 版本、多公司配置以及大型数据库。Odoo Online 仅在部分套餐中提供外部 API。Odoo 19 已弃用 /jsonrpc（计划于 2028 年秋季的 Odoo 22 和 2027 年冬季的 Odoo Online 21.1 中移除），转而使用 JSON-2 API；本服务尚未使用 JSON-2。Odoo 19 每次收到 /jsonrpc 调用时都会记录弃用警告。

开发

npm ci
npm test

proof/run-live.sh 18.0 会在一次性 Linux 机器上重复实时测试（该脚本会安装 PostgreSQL 和 Odoo；请勿在你的工作站上运行）。

安全

请参阅 SECURITY.md。请使用专用的 Odoo 用户，并仅授予助手所需的权限。

许可证

MIT，详见 LICENSE。