Odoo Assistant MCP 服务器

一个通过模型上下文协议（MCP）实现的 Odoo 虚拟员工。该服务器将 Odoo 的业务逻辑、记录和工作流暴露给大语言模型，使其能够安全地查询、创建、更新和对 Odoo 数据执行操作。

快速开始

1. 安装

直接运行服务器：

uvx odoo-assistant

或将其安装到您的环境中：

uv pip install odoo-assistant

如需从源码安装以进行开发，仍然可行：

uv pip install git+https://github.com/singleflo/odoo-assistant-mcp

2. 配置环境变量

需要设置两个变量；其余配置均会自动发现或存在默认值：

• ODOO_BASE_URL：您的 Odoo 实例的基础 URL（例如 https://mycompany.odoo.com）。

• ODOO_API_KEY：Odoo API 密钥（Odoo 14+，在 设置 > 用户 > API 密钥 > 新建 中生成）。不接受账户密码：密钥针对每个用户，可独立设置范围和撤销。

可选配置：

• ODOO_DB：数据库名称。当实例只提供一个数据库时自动发现；如果提供多个数据库则需要填写——错误信息会列出所有数据库名称。

• ODOO_USER：登录名。通过密钥发现最多需要额外 59 次往返；如果密钥所有者的 uid 为 60 或更高，则发现失败。设置此变量可跳过探测。

• ODOO_MCP_MAX_LEVEL：此服务器可执行的最高安全级别，范围为 0 到 4（默认：3）。通过此设置可将服务器设为只读或允许删除——参见选择上限。

• ODOO_MCP_PROTECTED_HOSTS：此服务器拒绝写入的主机列表（以逗号分隔，默认为空——此包未内置任何主机）。列出的主机仍允许读取；写入需要设置 ODOO_ALLOW_PROD_WRITE=yes 作为有意为之的覆盖。

Related MCP server: mcp-server-odoo

安全层

每次写入和操作在到达 Odoo 之前都会经过动态安全分类器。操作被分为 L0 到 L5 级别：

选择上限

ODOO_MCP_MAX_LEVEL 设置此服务器可执行的最高级别。每个值都是累积的——它允许自身级别及以下所有级别：

在选取数值之前，需要了解两种行为：

• 5 不会解锁 L5。 两个 L5 变体在读取上限之前就会被拒绝。L5_PRIVATE 被拒绝是因为 Odoo 自身会拒绝所有以 _ 开头的方法，因此任何上限都无法传递它；L5_UNKNOWN 被拒绝是因为未经分类的方法，其效果自然未经验证。允许此类方法的途径是将它添加到 safety_layer.py 中的 WRITE_L1/L3/L4 中——通过代码审查，绝不通过配置。

• 无效值将拒绝启动。 ODOO_MCP_MAX_LEVEL="O" 会引发错误而非回退到默认值，因为默认值允许写入：一个拼写错误绝不能让你得到一个你认为是只读的写入服务器。

上限由人类通过外部方式设定，并在启动时从进程环境读取。运行在此服务器上的模型无法提高它；当调用超过上限时，拒绝信息会指出所需级别，以便代理能够解释操作会改变什么，并将决定权留给你。

请注意，这是此服务器的权限，而非账户的权限。拥有 shell 访问权限的代理始终可以通过直接调用 Odoo 来绕过 MCP 服务器。无论客户端如何都必须保持的限制应归属于 API 密钥所属用户的 Odoo 访问权限中，由 Odoo 服务器强制执行。

Odoo 版本支持

Odoo 14.0 是支持的最低绝对版本，因为此服务器仅使用 API 密钥进行身份验证，而 Odoo 13 及更早版本中不存在 API 密钥。

API 密钥生成路径

要生成 API 密钥，请登录到您的 Odoo 实例并导航至： 偏好设置 / 我的个人资料 → 账户安全 → 新建 API 密钥

传输与弃用说明

客户端会自动检测原生 JSON-2 API 是否可在 /json/2/<model>/<method> 上使用（该接口使用 Authorization: bearer <API_KEY>），如果不可用则回退到 XML-RPC。请注意，XML-RPC 和 JSON-RPC 已在 Odoo 19 中弃用，并计划在 Odoo 22 中移除。

来源

• Odoo 14.0 外部 API 文档（API 密钥介绍）

• Odoo 19.0 外部 API 文档（JSON-2）

• Odoo 19.0 外部 RPC API 文档（XML-RPC 弃用）

• Odoo 标准与扩展支持政策（支持时间线）

工具和资源

该服务器公开 19 个工具和 2 种资源类型：

工具

1. search_read：在一次调用中搜索并读取记录（Odoo search_read）。

2. read_record：按 ID 读取一条记录，始终使用指定字段。

3. count_records：统计与域匹配的记录数（Odoo search_count）。

4. instance_overview：汇总已连接实例的信息：版本、公司、各区域量、内部模块、异常。

5. required_fields：列出 Odoo 在模型上执行 create 之前要求的字段、它将应用的默认值以及现有记录实际如何使用该字段。

6. create_record：创建记录，当指定 unique_on 时重用现有匹配项。

7. write_record：向一条记录写入字段值，并报告实际更改的内容。

8. run_action：运行一个工作流方法并报告它留下的状态。

9. cancel_record：通过 action_cancel 取消记录，跟随其返回的向导。

10. notify_user：在记录的讨论区通知用户。默认为内部通知。

11. create_activity：安排一个活动：唯一带有截止日期的通知。

12. download_docs：将记录的所有文档保存到磁盘，包括讨论区文件。

13. generate_pdf：渲染记录的 PDF 并返回保存位置。

14. list_message_targets：列出哪些人可以接收消息以及在哪里——具有在线/离开/离线状态的内勤用户以及调用者的开放对话。发送前请先询问此工具。

15. read_conversation：阅读讨论对话，最新优先。

16. send_direct_message：发送一对一的讨论消息，该消息会实时出现在用户的聊天系统托盘中——无需电子邮件，无论他们的通知设置如何都能收到。

17. send_channel_message：发布到现有的讨论频道，拒绝包含非员工的房间。

18. explore_module：通过询问实时实例来发现模块的结构。

19. list_known_modules：列出此服务器已了解的模块：名称、生成日期、记录数。

工具 10-11（notify_user、create_activity）通知关于一条记录并落在收件箱铃铛中；工具 14-17 是讨论对话，落在聊天系统托盘中。“给用户 X 发消息”是第二种——使用 send_direct_message，而不是 notify_user。

资源

• odoo://skill：访问 Odoo 助手技能说明。

• odoo://ref/*：访问已探索模块的生成参考文档。

主机配置示例

以下每个示例仅包含重要内容：两个必需的变量以及上限——决定此服务器能否写入的唯一设置，在人类拥有的文件中可见。数据库和登录名会自动发现，3 是上限的默认值。注意引号：环境值是字符串。

Claude Desktop

将此添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

Cursor

将此添加到您的 .cursor/mcp.json 或在 Cursor 设置界面配置：

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

VS Code Copilot

将此添加到您的 VS Code settings.json：

{
  "mcp.servers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

opencode

将此添加到项目中的 opencode.json 或 .opencode/opencode.json，或添加到 ~/.config/opencode/opencode.json 以使该服务器在所有地方可用：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "odoo-assistant": {
      "type": "local",
      "enabled": true,
      "command": [
        "uvx",
        "odoo-assistant"
      ],
      "timeout": 120000,
      "environment": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

opencode 的结构与上述主机在方式上有所不同，这些差异会导致直接拒绝：键是 mcp（而非 mcpServers），type 是必需的，command 是一个包含程序和其参数的单个数组（没有单独的 args），而环境块是 environment（而非 env）。

请有意设置 timeout。其默认值为 5000 ms，会话的第一次调用需要身份验证，加上对于 instance_overview 来说，需要数十次 XML-RPC 往返——在真实实例上轻松超过五秒。

opencode 在启动时读取一次配置，并且不会热重载，因此编辑后请退出并重新启动。您在此处更改的任何内容（包括上限）仅在下次启动时生效。

ChatGPT（自定义连接器）

要通过自定义连接器将此服务器连接到 ChatGPT：

1. 前往设置 → 连接器 → 添加连接器。

2. 输入服务器 URL 或从注册表中选择。

3. 提示时输入你的 Odoo 凭据。

Hermes

使用 Hermes CLI 添加服务器：

hermes mcp add odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_MCP_MAX_LEVEL=3 \
  --args run odoo-assistant

这些示例省略了可选变量。当实例提供多个数据库时设置 ODOO_DB，设置 ODOO_USER 以跳过 uid 探测，设置 ODOO_MCP_MAX_LEVEL 将上限从默认的 3 更改。

许可证

本项目基于 MIT 许可证授权。详情请参阅 LICENSE 文件。