odoo-assistant

Odoo 版 Singleflo

通过模型上下文协议（MCP）接入 Odoo 的虚拟员工，以 odoo-assistant 包的形式发布。此服务将 Odoo 的业务逻辑、记录和工作流提供给大模型，使它们能够安全地查询、创建、更新和操作 Odoo 数据。

Singleflo for Odoo 是一个独立项目，与 Odoo S.A. 无关联，也未获其认可或赞助。Odoo 是 Odoo S.A. 的商标，此处提及仅用于说明此服务所适配的软件。

快速入门

通过 AI Agent 安装。 如果你的电脑上已有 AI 助手——Hermes、Claude Code、Claude Desktop、Codex、Cursor、opencode 或下方列出的任意宿主——请将此提示词作为一条消息粘贴进去：

Please install "Singleflo for Odoo" (the MCP server `odoo-assistant`) so that you can work with my Odoo.
Open and follow, step by step, the instructions written for you at:
https://raw.githubusercontent.com/singleflo/odoo-assistant-mcp/main/docs/INSTALL-WITH-YOUR-AGENT.md
I am not technical. Talk to me in English, give me one simple step at a time and wait for my answer, and do all the technical work yourself.
When you need the Odoo API key, guide me through creating it screen by screen. Never ask me for my Odoo password.
At the end, check that you can read my Odoo and tell me what you set up.

同一提示词的意大利语、西班牙语和捷克语版本见 docs/INSTALL-PROMPT.md。该页面面向 Agent，而非你：它会询问你的 Odoo 地址，指导你创建 API 密钥，在 Odoo Online 上查找数据库名称，安装 uv，写入其宿主会读取的配置文件，并验证连接。对于无法安装任何内容的 Claude.ai 或 ChatGPT，它会引导你使用托管连接。手动安装方法见下文。

1. 安装

直接运行此服务：

uvx odoo-assistant

或者将其安装到你的环境中：

uv pip install odoo-assistant

仍可从源代码安装以进行开发：

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

2. 配置环境变量

还没有 API 密钥？

如何创建 Odoo API 密钥 → — 共七个步骤，每个步骤都配有一张 截图。

简而言之：头像 → 首选项 → 账户安全 → 新建 API 密钥。它绝不是你的账户密码，只属于一个 Odoo 用户，并且具有该用户的全部权限；Odoo 只会显示一次密钥值。

• ODOO_BASE_URL：始终必填。Odoo 实例的基础 URL，末尾不要加斜杠（例如，https://mycompany.odoo.com）。
• ODOO_API_KEY：始终必填。Odoo API 密钥（Odoo 14+ — 参见上方说明框，或 docs/api-key.md）。不接受账户密码。密钥按用户分配、受权限范围限制，并且可以单独撤销。Odoo 19 还要求填写说明并设置有效期，最长为 3 个月。
• ODOO_DB：Odoo Online（SaaS，*.odoo.com）上必填，其他情况可选。Odoo Online 上，数据库列表端点已禁用。自动发现无法找到数据库名称，且每次工具调用都会失败，只显示含糊的“执行工具时出错”，不会提示问题出在数据库。设置 ODOO_DB 后，同一配置即可立即连接。SaaS 数据库名称并非好记的子域名，而是带后缀的名称，格式类似 mycompany16-prod-12345678 — 你可以在 /web/database/selector 或 Odoo.com 账户页面找到它。其他情况下，如果实例恰好提供一个数据库，系统会自动发现；如果提供多个数据库，则必须设置此项。
• ODOO_USER：绝不必填。省略时，客户端会查询 res.users 中 uid 1 到 59 的用户，并保留密钥对应的用户。这会在首次调用时增加最多 59 次额外往返；如果密钥所有者的 uid 为 60 或更高，则会直接失败。设置此项即可避免这笔开销。它必须是登录名（例如，[email protected]），如果值不正确，Odoo 的 authenticate() 会返回 False，而不是抛出异常 — 这看起来像是权限错误。
• ODOO_MCP_ALLOW：可选，默认值为 * — 允许拒绝列表未拒绝的所有方法。单独设置为 none 时，服务将变为只读；当 Agent 需要读取实时公司数据时，建议使用此设置。其他值均为以逗号分隔的方法名称列表。参见下文“Agent 可以执行的操作”。
• ODOO_MCP_DENY：可选。未设置时，将使用默认拒绝列表 — unlink、archive、action_cancel、button_cancel、action_reverse、action_draft、mailing.mailing:action_send。设置该值后，原列表将被完全替换。参见下文“Agent 可以执行的操作”。
• ODOO_MCP_ALLOW_UNLINK：可选，默认关闭。设置为 yes、true 或 1（不区分大小写）即可允许 unlink；任何一个列表中的条目都无法允许此操作。参见下文“Agent 可以执行的操作”。
• ODOO_MCP_DATA_DIR：可选。此服务存放所有写入内容的位置，包括实例配置文件。默认使用平台自带的数据目录 — Windows 上为 %LOCALAPPDATA%\odoo-assistant，macOS 上为 ~/Library/Application Support/odoo-assistant，其他平台上为 $XDG_DATA_HOME/odoo-assistant（否则为 ~/.local/share/odoo-assistant）。

Agent 可以执行的操作

每次写入和每项操作在到达 Odoo 之前，都会经过一道关卡。关卡会根据调用的 METHOD NAME，对照你在主机配置文件中自行设置的两个列表进行判断，并在调用时从进程环境中读取这两个列表：

• ODOO_MCP_ALLOW — 允许执行的内容。未设置或为空表示 *：除被拒绝列表拦截的方法外，所有方法都允许执行。单独设置为 none 会使服务变为只读。
• ODOO_MCP_DENY — 禁止执行的内容。未设置或为空时使用默认列表：unlink、archive、action_cancel、button_cancel、action_reverse、action_draft、mailing.mailing:action_send。你设置的值会完全替换该列表，而不是在其基础上追加，因此生效的拒绝项恰好是你自己的文件中列出的名称——ODOO_MCP_DENY=unlink 就是重新允许 action_cancel 的设置方式。

条目可以是 method，表示匹配每个模型上的该方法；也可以是 model:method，表示只匹配某个模型上的该方法。匹配采用精确的字符串相等，不支持前缀或子串，因此 action_send 永远不会匹配 action_send_and_print，action_cancel 也永远不会匹配 button_cancel。这些确切名称均由人工审核并批准；如果匹配规则过于宽松，就会放过无人审核过的相似名称。先检查拒绝列表，再检查允许列表，因此同时出现在两个列表中的名称会被拒绝。

按模型限定是实际案例的需要。在一个运行中的实例上，有 31 个模型响应 action_send，而只有 Evolution 向导应该响应——mailing.mailing 上的该方法一次调用就能向整个客户群发送电子邮件。这就是为什么默认拒绝列表将该条目写作 mailing.mailing:action_send，而让其他地方的 action_send 继续正常工作。

另有四条规则不受这些列表影响：

• unlink 在检查这两个列表之前就会被处理。 无论 ODOO_MCP_ALLOW 或 ODOO_MCP_DENY 的值是什么，都不能授权删除；只有 ODOO_MCP_ALLOW_UNLINK 可以——值为 yes、true 或 1 均可，且不区分大小写。删除是唯一无法撤销的操作，因此逗号分隔列表中的名称绝不能单独成为授权依据。
• archive 是一个虚拟名称。 action_archive 和带有 active: False 的 write 都会以该名称接受列表检查，因此拒绝 archive 就会拒绝隐藏记录，不论具体操作使用什么名称。
• 私有方法始终会被拒绝，不受列表内容影响。Odoo 本身会拒绝所有以 _ 开头的方法，因此任何列表都无法放行此类方法。
• 读取操作不会经过这两个列表，因为读取不会产生列表需要管控的影响。account.move 结构性防护不受这些规则影响，仍适用于读取操作：如果查询混合了发票、账单和日记账分录，无论列表内容如何，都会被拒绝，因为无意义的读取本身就是一种风险。

配置	允许的操作
ODOO_MCP_ALLOW=none	仅允许读取。此服务无法执行任何会更改记录的操作——适用于连接到生产环境实时数据的 Agent。
未设置任何内容	默认设置。 除默认拒绝列表中的七个方法外，其他方法均可执行：创建、写入、确认订单、过账发票、安排活动、向用户发送消息。
ODOO_MCP_ALLOW_UNLINK=yes	默认设置，外加 unlink。拒绝列表保持不变，因此在你自行设置 ODOO_MCP_DENY 之前，archive 和 action_cancel 仍会被拒绝。

这些列表由人工在带外设置，运行在此服务上的模型无法更改它们。当关卡拒绝操作时，拒绝原因会指出调用、作出判断的条目，以及能够改变判断结果的变量，因此 Agent 可以说明该操作会产生什么影响，并将决定权留给你。

请注意，这是此服务的权限，而不是账户的权限。拥有 shell 访问权限的 Agent 始终可以绕过 MCP 服务，直接调用 Odoo。若要设置无论客户端为何都必须遵守的限制，应将其配置在 API 密钥所属用户的 Odoo 访问权限中，由 Odoo 服务端强制执行。

数据库和登录：何时必须设置

在所有情况下，都只需要设置 ODOO_BASE_URL 和 ODOO_API_KEY。ODOO_DB 和 ODOO_USER 会自动发现，而能否成功发现取决于你的实例托管方式。

数据库会按以下顺序分两步查找：先对 /xmlrpc/db 调用 list()，然后发送 /web/session/get_session_info POST 请求；该请求无需凭据，即使 list_db = False 隐藏了数据库列表，也仍会报告数据库名称。系统不会要求提供登录名——API 密钥恰好属于一个用户，而 execute_kw 只有搭配该用户的 uid 才能接受此密钥，因此客户端会通过探测 uid 1 到 59 的 res.users 来查找密钥所有者。

托管方式	ODOO_DB	ODOO_USER	原因
Odoo Online（*.odoo.com，SaaS）	必填	可选	实测：此处禁用了数据库列表端点；如果没有数据库名称，所有工具调用都会失败，并显示含糊的“执行工具时出错”，完全不会提示问题出在数据库上。SaaS 数据库名称不是子域名——它带有后缀，格式类似 mycompany16-prod-12345678，可在 /web/database/selector 中找到。
Odoo.sh	可选	可选	一个分支只提供一个数据库，且会话信息回退方案会报告其名称。尚未在实际运行的分支上测试：如果首次调用失败，请设置此项。
本地部署，单个数据库	可选	可选	无论通过哪一步发现，都会返回唯一的名称。
本地部署，多个数据库	可选，但设置起来更方便	可选	并非必填：发现失败时，错误信息会列出找到的数据库名称并提示你选择一个，因此失败原因一目了然。设置此项可跳过这次往返请求，消除歧义。

在任何托管方式下，单独设置 ODOO_USER 都不是必需的。设置此项可在会话的首次调用中最多节省 59 次发现往返请求；如果 API 密钥所有者的 uid 为 60 或更高，则此项会变为 必填，因为发现过程只会探测 uid 1 到 59。此项必须填写登录名（例如 [email protected]），而且填写错误时很容易误导人：对于未知登录名，Odoo 的 authenticate() 会返回 False 而不是抛出错误，因此拼写错误看起来像权限错误，而不是拼写错误。

按 Odoo 版本

Odoo 14 到 18 在此处的行为完全相同。 XML-RPC 会在每次 execute_kw 调用中携带数据库 名称，因此客户端必须在认证之前知道该名称——这正是需要发现数据库的原因。

Odoo 19 新增了 JSON-2 API，它通过 X-Odoo-Database HTTP 标头选择数据库。Odoo 官方页面上的标头表将其列为可选项，而页面的数据库部分则具体说明了何时它会变为必填项：当“单个 Odoo 服务器托管多个数据库，且未将 dbfilter 配置为使用 Host 标头”时必填；或者用同一页面其他位置的说法，只有在“同一域名可访问多个数据库的系统上”，才“必须通过 X-Odoo-Database HTTP 标头提供”数据库名称。如果主机名本身已能选定数据库——例如 Odoo Online、Odoo.sh，或任何按 Host 匹配的 dbfilter——则可以省略该标头。

此服务器的客户端会优先尝试 JSON-2：发送一个包含 Authorization: Bearer <key> 的 POST /json/2/res.users/search_count 请求；如果返回 200，则本次会话使用 JSON-2 作为传输方式；否则回退到 XML-RPC。它只发送 Authorization 和 Content-Type，不会发送其他内容，因此不会设置 X-Odoo-Database——使用 JSON-2 时，主机必须自行解析数据库，而 ODOO_DB 只会用于 XML-RPC 路径。

Odoo 版本支持

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

Odoo 版本	API 密钥	XML-RPC	官方维护中（2026 年 8 月）	支持级别 / 备注
≤ 13.0	否	是	否	不支持。该版本没有 API 密钥，因此此服务无法进行身份验证。
14.0	是	是	否	协议兼容。未经实时实例测试。
15.0	是	是	否	协议兼容。未经实时实例测试。
16.0	是	是	否	已在实时企业版实例上验证：连接、身份验证、读取、instance_overview 和 Discuss 工具。两个代际差异已为你处理，详见下方说明。未测试写入场景。
17.0	是	是	是（截至 2026 年 9 月）	协议兼容。未经实时实例测试。
18.0	是	是	是（截至 2027 年 9 月）	主要目标版本。已在实时实例上验证并提供全面支持。
19.0	是	是	是（截至 2028 年 9 月）	协议兼容。未经实时实例测试。API 密钥需要设置说明和有效期（最长 3 个月）。JSON-2 API 通过 X-Odoo-Database 标头选择数据库，详见上文“数据库和登录：何时必须设置”。

Odoo 16 和 17 之间有两项变化，均无需配置：

• Discuss 更名了。17 版将 mail.channel / mail.channel.member 改为 discuss.channel / discuss.channel.member。服务会查询实例使用的名称组合并据此操作，因此四个 Discuss 工具均适用于这两个代际。
• 订阅功能迁移到了 sale.order，而 17 版之前该模型完全没有 subscription_state 字段。在 16 版中，instance_overview 中不会显示该部分——这是正常缺失，而非故障。

API 密钥生成路径

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

图文操作指南见 docs/api-key.md，其中还介绍了有效期字段、Odoo 19 的有效期规则以及如何撤销密钥。

传输方式与弃用说明

客户端会自动检测 /json/2/<model>/<method> 是否提供原生 JSON-2 API（该 API 使用 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 标准与扩展支持政策（支持时间表）

工具和资源

此服务提供 22 个工具和 2 种资源类型：

工具

1. search_read：一次调用即可搜索并读取记录（Odoo search_read）。
2. read_record：按 ID 读取一条记录，始终使用命名字段。
3. read_long_field：分段读取一个长文本字段，因此即使值超过 5000 个字符的结果上限，也能完整读取。
4. count_records：统计符合某个域条件的记录数（Odoo search_count）。
5. group_records：按组分组记录，并统计（或聚合）每个分组的结果（Odoo read_group）——按状态、阶段或月份汇总。
6. instance_overview：汇总已连接实例的信息：版本、公司、各领域的数据量、自研模块和异常。
7. required_fields：列出 Odoo 在对某个模型执行 create 前要求的字段、会应用的默认值，以及现有记录的实际用法。
8. describe_model：列出实时实例定义的模型字段：名称、类型、关系、选项值，以及必填标记。
9. create_record：创建记录；如果提供了 unique_on，则复用匹配的现有记录。
10. write_record：写入一条记录的字段值，并报告实际发生的更改。
11. run_action：运行工作流方法，并报告执行后留下的状态。
12. cancel_record：通过 action_cancel 取消记录，并处理该操作返回的向导。
13. notify_user：在记录的 chatter 中通知用户。默认仅内部可见。先预览，只有获得用户批准后才发布（见下文）。
14. create_activity：安排一项活动：这是唯一包含截止日期的通知。
15. download_docs：将记录的所有文档保存到磁盘，包括 chatter 文件。
16. generate_pdf：生成记录的 PDF，并返回保存位置。
17. list_message_targets：列出可发送消息的对象和位置，包括显示在线状态（在线／离开／离线）的内部用户，以及调用者未关闭的会话。发送前先调用此工具。
18. read_conversation：按时间倒序读取 Discuss 会话。
19. send_direct_message：发送一对一 Discuss 消息，实时显示在用户的聊天托盘中。此操作不会发送电子邮件，无论用户的通知设置如何，消息都会送达。先预览，只有获得用户批准后才发送。
20. send_channel_message：向现有 Discuss 频道发消息；如果频道中有非员工，则拒绝发送。先预览，只有获得用户批准后才发布。
21. explore_module：通过查询实时实例来了解模块结构。
22. list_known_modules：列出此服务已了解的模块：名称、生成日期和记录。

工具 13–14（notify_user、create_activity）用于通知某条记录的相关信息，通知会显示在收件箱铃铛中；工具 17–20 用于 Discuss 会话，消息会显示在聊天托盘中。“给用户 X 发消息”属于第二种，应使用 send_direct_message，而不是 notify_user。

代表用户发送消息的三个工具——notify_user、send_direct_message、send_channel_message——都需要调用两次。第一次调用时不提供 confirmation_token，不会发送任何内容：工具会验证请求，并返回预览（接收者、发送渠道、哪些人会收到电子邮件、完整消息）和令牌。Agent 展示预览并征求用户同意；只有用户批准后，才会使用相同参数和令牌再次调用。令牌仅批准预览中的确切参数，只能使用一次，有效期为 10 分钟；因此，批准后若修改了消息，请求会被拒绝，而不会发送。

资源

• odoo://skill：访问 Odoo 助手技能说明。
• odoo://ref/*：访问已探索模块的生成式参考文档。

主机配置示例

以下每个示例只包含重要内容：两个必需变量，以及在 Odoo Online 上无法通过发现机制获取的数据库。登录信息会自动发现；除非添加 ODOO_MCP_ALLOW 或 ODOO_MCP_DENY，否则权限门会使用默认设置——请参阅“Agent 可以执行哪些操作”。注意引号：环境变量的值都是字符串。

每个代码片段中都包含 ODOO_DB，因为很多人在无法正常工作时，缺少的正是这个变量。仅在必需时设置它——请参阅上文“数据库和登录信息：何时必须设置”。JSON 不允许添加注释，所以相关说明放在这里，而不是代码块中；TOML 和 YAML 代码片段则附有行内说明。

以下每个代码片段都已根据对应主机自己的文档进行核对，引用见其下方的 Source: 行。如果主机提供单行添加命令，也会一并给出，因为它可以直接写入相同的配置项，无需手动编辑文件。

托管服务：Claude.ai、ChatGPT 和 Codex

以下各节中的所有配置，都会在你的计算机上运行服务。还有另一种方式可以使用相同的 22 个工具：它们也通过互联网在 https://odoomcp.singleflo.com/mcp 上提供服务，Claude.ai、ChatGPT 和 Codex 都可以直接访问。你无需安装任何东西，也无需在自己的环境中设置变量——只需在服务的授权页面上使用 Odoo 地址和 API 密钥登录一次，你正在使用的聊天工具就能访问你的 Odoo。其他所有章节中的本地配置仍会按原样正常工作；这两种方式的唯一区别是服务运行的位置。

ChatGPT 插件目录中的条目连接到 https://odoomcp.singleflo.com/openai/mcp：使用相同的服务、登录方式和策略，但不提供 run_action 和 explore_module 这两个工具，因为 OpenAI 不允许使用它们：前者可以运行任意工作流方法，后者可以通过一个参数在两项操作之间进行选择。Claude.ai、Codex 和 ChatGPT 开发者模式仍使用 /mcp，并可使用全部 22 个工具。

授权页面会要求你提供 Odoo URL、API 密钥，并选择一种权限：读取允许 Agent 查看数据，标准还允许其创建记录、运行工作流和安排活动。托管服务始终不提供删除功能——无论选择哪种权限，都无法通过它访问 unlink。之后可以重新登录并选择另一种权限来更改设置。

此外还有两个可选字段，原因与本地设置 ODOO_DB 和 ODOO_USER 相同：数据库，在 Odoo Online 上必需；以及密钥所属用户的 Odoo 登录名。留空登录名时，服务会尝试通过探测 uid 1 到 59 来确定所有者；如果这种探测无法找到用户，请填写登录名——实例设置完成很久之后才创建的用户，其 uid 可能大于 59，此时如果不填写登录名，就无法登录。发生这种情况时，页面会提示你。

托管服务存储的内容：你的 Odoo URL 和 API 密钥（以加密形式静态存储）；你的登录身份（仅以哈希形式保存）；以及工具生成的文件（只以链接形式保存在服务上，15 分钟后过期）。详情请见 https://odoomcp.singleflo.com/privacy，同一域名下还有 https://odoomcp.singleflo.com/terms 和 https://odoomcp.singleflo.com/support。

各主机的说明：Claude.ai 和 ChatGPT 仅支持托管连接，并各自在下方设有专门章节。Claude Code 和 Codex 保留上文的本地配置，并且各新增了一条托管服务的一行命令。

如果你更愿意自行运行托管部分，请参阅开发者指南 docs/REMOTE.md，其中涵盖了完整流程——本地运行、隧道和部署。

Claude Desktop

Claude Desktop 仅提供 macOS 和 Windows 版本，服务器配置保存在 claude_desktop_config.json 中。可通过 Settings → Developer → Edit Config 打开配置文件，也可以直接编辑其所在位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\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_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

完全退出 Claude Desktop 并重新打开：它会在启动时读取文件，不会重新加载。服务器日志在 macOS 上保存在 ~/Library/Logs/Claude/，在 Windows 上保存在 %APPDATA%\Claude\logs，每个服务器对应一个文件。stdio 服务器会将其输出的所有内容写入其中的 stderr。

来源：https://modelcontextprotocol.io/docs/develop/connect-local-servers

Claude Code

添加一行即可添加服务器。-- 用于分隔 Claude Code 自身的选项和启动服务器的命令，之后的内容都会原样传递：

claude mcp add --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_DB=mycompany16-prod-12345678 \
  --transport stdio odoo-assistant -- uvx odoo-assistant

请注意顺序。--env 接受 KEY=value 键值对，并会持续读取，因此服务器名称不能紧跟在它后面——至少要在两者之间加一个其他选项，此处使用 --transport stdio，否则 CLI 会将 odoo-assistant 读作另一个键值对并拒绝它。

--scope 决定配置项的写入位置：local（默认值：仅此项目，仅你可用）、project（仓库根目录下的 .mcp.json，提交后可共享），或 user（所有项目）。如需手动填写，可将相同的配置项写入 .mcp.json 或 ~/.claude.json 中的 mcpServers 下：

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      },
      "timeout": 120000
    }
  }
}

每个服务器的 timeout 是单次工具调用的墙钟时间限制，单位为毫秒；它仅对该服务器生效，并会覆盖 MCP_TOOL_TIMEOUT 环境变量。另一个以毫秒为单位的 MCP_TIMEOUT 则限制服务器启动时间。此处只有在会话中首次调用 instance_overview 时才需要关注这些设置，因为该调用需要完成身份验证并执行数十次 XML-RPC 往返。编辑后，可在 /mcp 面板中重新连接服务器，或重启 Claude Code。

上面的一行命令会在你的计算机上运行服务器。Claude Code 也可以使用托管服务器，无需安装或设置环境变量：

claude mcp add --transport http odoo-assistant https://odoomcp.singleflo.com/mcp

首次调用工具时会启动登录流程，并跳转到选择 read 或 standard 的授权页面。使用托管方式时，权限由该页面上的选择决定，而不是由本地 ODOO_MCP_* 变量决定，并且完全不提供删除功能。

来源：https://code.claude.com/docs/en/mcp

OpenAI Codex CLI

Codex 使用 TOML 保存 MCP 服务器配置，文件位于 ~/.codex/config.toml；信任某个项目后，也可将配置保存在该项目的 .codex/config.toml 中。配置表的名称带下划线——mcp_servers，而不是 mcp.servers。ChatGPT 桌面应用、Codex CLI 和 IDE 扩展都读取同一个文件，因此配置一次即可供这三者使用。

codex mcp add odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_DB=mycompany16-prod-12345678 \
  -- uvx odoo-assistant

以下是展开后的相同配置项：

[mcp_servers.odoo-assistant]
command = "uvx"
args = ["odoo-assistant"]
startup_timeout_sec = 30
tool_timeout_sec = 300

[mcp_servers.odoo-assistant.env]
ODOO_BASE_URL = "https://mycompany.odoo.com"
ODOO_API_KEY = "your-api-key-here"
# only when required, see "Database and login" above
ODOO_DB = "mycompany16-prod-12345678"

两个超时时间的单位都是 秒：startup_timeout_sec 默认值为 10，tool_timeout_sec 默认值为 60。只有首次调用 instance_overview 时才可能接近任一限制，因此上面调高了这两个值。编辑后，在桌面应用或 IDE 扩展中点击服务器旁的 Restart；在 CLI 中，则启动新会话并使用 /mcp 检查。

托管服务器则通过 URL 添加，并需单独运行登录命令：

codex mcp add odoo-assistant --url https://odoomcp.singleflo.com/mcp
codex mcp login odoo-assistant

codex mcp login 会引导你完成相同的 OAuth 流程，并跳转到选择 read 或 standard 的授权页面；codex mcp logout odoo-assistant 则会断开连接。与所有托管方式一样：始终可以读取，写入权限取决于登录时的选择，并且完全不提供删除功能。

来源：https://developers.openai.com/codex/mcp

来源：https://developers.openai.com/codex/config-file/config-reference

ChatGPT

ChatGPT 通过 开发者模式 连接托管服务。Pro、Plus、Business、Enterprise 和 Education 账户可在网页版使用：

1. 在 ChatGPT 中，打开 设置 → 安全与登录，然后启用 开发者模式。
2. 打开 chatgpt.com/plugins，点击加号按钮，为 MCP URL https://odoomcp.singleflo.com/mcp 创建一个开发者模式应用。
3. ChatGPT 会启动登录流程，并跳转到服务的授权页面：输入你的 Odoo URL 和 API 密钥，然后选择 只读或标准。
4. 在对话中，从加号菜单选择 开发者模式，然后选择 Singleflo for Odoo 应用。

这里特意没有提供本地配置片段：开发者模式仅通过 HTTPS 连接远程 MCP 服务，因此其他部分中的 stdio 配置不适用。计划在 ChatGPT Plugin Directory 中公开上架，这样就无需开发者模式步骤，但目前尚未推出。

Agent 可执行的操作在登录时一次性确定：只读或标准——无论对话中如何要求，都不会删除数据。

来源：https://developers.openai.com/plugins/deploy/connect-chatgpt

Claude.ai（网页版、桌面版、移动版）

Claude 通过自定义连接器连接托管服务。打开 自定义 → 连接器 → 添加自定义连接器，将 https://odoomcp.singleflo.com/mcp 粘贴为服务 URL，然后确认。对于 Team 和 Enterprise 方案，组织所有者需在 组织设置 → 连接器 中添加一次；成员之后便可从 自定义 → 连接器 进行连接。

首次使用时会启动登录流程，并跳转到授权页面：填写你的 Odoo URL、API 密钥，并选择只读或标准。

此链接会打开同一个对话框，且名称和 URL 已预先填入——请检查并确认；在你确认之前，不会添加任何内容：

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Singleflo%20for%20Odoo&connectorUrl=https%3A%2F%2Fodoomcp.singleflo.com%2Fmcp

来源：https://claude.com/docs/connectors/custom/remote-mcp

来源：https://claude.com/docs/connectors/building/directory-vs-custom

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_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

opencode 的配置格式与上述主机不同，若格式不符会直接拒绝。键名是 mcp（而非 mcpServers）；必须指定 type；command 是一个包含程序及其参数的数组（没有单独的 args）；环境变量区块是 environment（而非 env）。

请谨慎设置 timeout。其默认值为 5000 ms。会话中的首次调用需要进行身份验证；对于 instance_overview，还要进行数十次 XML-RPC 往返，因此面对真实实例时很容易超过 5 秒。请将其设为 120000。

opencode 会在启动时读取一次配置，不会热重载。编辑后请退出并重新启动。你在此处所做的任何更改，包括允许和拒绝列表，都要到下次启动时才会生效。

来源：https://opencode.ai/docs/mcp-servers

Hermes

Hermes 使用 YAML 保存服务器配置，位于 ~/.hermes/config.yaml 的 mcp_servers: 下：

mcp_servers:
  odoo-assistant:
    command: /Users/you/.local/bin/uvx
    args:
      - odoo-assistant
    env:
      ODOO_BASE_URL: https://mycompany.odoo.com
      ODOO_API_KEY: your-api-key-here
      # only when required, see "Database and login" above
      ODOO_DB: mycompany16-prod-12345678
    timeout: 120
    connect_timeout: 60
    enabled: true

这种配置格式有三个不可变更之处。command 是一个字符串，只能填写程序，参数需放在单独的 args 列表中——这与 opencode 的单个数组正好相反。环境变量块是 env。此外，命令必须使用绝对路径：Hermes 作为桌面应用运行，不会继承 shell 的 PATH，因此无法找到裸写的 uvx。

这里的两个超时值都以秒为单位，而不是毫秒：timeout 是工具调用时限，默认为 300；connect_timeout 限制初始连接时间，默认为 60。上面的 120 对首次调用 instance_overview 来说绰绰有余。编辑后使用 /reload-mcp 重新加载服务器，而不是重启。

hermes mcp add 可以为你写入此配置项——其用法为 add <name> [--url URL] [--command CMD] [--auth oauth|header] [--args ...]—— 但要把 --args 放在最后：它会接收剩余的 argv，因此其后的内容都会被吞进 args，导致凭据被放入其中，服务器启动时却没有凭据。

来源：https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference

Cursor

将此配置添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以便在所有位置使用该服务器；也可以在侧边栏的 Customize 中进行配置：

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

Cursor 会在 command、args、env、url 和 headers 中插值 ${env:NAME}，因此 "ODOO_API_KEY": "${env:ODOO_API_KEY}" 可以避免将密钥写入可能提交的文件。调用失败时，可在 Output 面板的 MCP Logs 下查看原因。

来源：https://cursor.com/docs/context/mcp

Windsurf

Windsurf 的 Cascade Agent 在所有平台上都会读取一个全局文件—— ~/.codeium/windsurf/mcp_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_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

可通过 Cascade 面板中的 MCPs 图标，或通过 Settings → Cascade → MCP Servers 打开该文件，然后刷新服务器列表。文件会在 command、args 和 env 中插值 ${env:VAR_NAME} 和 ${file:/path/to/file}，因此 API 密钥可以存放在文件之外。Cascade 将 Agent 可用的工具总数限制为 100 个，而此服务器占 22 个。

来源：https://docs.windsurf.com/windsurf/cascade/mcp

VS Code 和 GitHub Copilot

VS Code 的根键是 servers，而不是 mcpServers——照搬其他主机文档中的配置项将无法识别。将其放入工作区中的 .vscode/mcp.json，以便与项目一同提交；或者在命令面板中运行 MCP: Open User Configuration，使用会随用户配置文件应用到每个工作区的配置：

{
  "servers": {
    "odoo-assistant": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

也可以通过命令行写入相同的配置项：

code --add-mcp "{\"name\":\"odoo-assistant\",\"command\":\"uvx\",\"args\":[\"odoo-assistant\"]}"

VS Code 首次启动服务器时会询问你是否信任它；如果拒绝，服务器将永远不会运行。使用 mcp.json 中的代码透镜，或在命令面板中运行 MCP: List Servers，即可启动、停止和重启服务器，并查看其输出。不要在已提交的工作区文件中硬编码 API 密钥——VS Code 提供的输入变量正是为此设计的。

来源：https://code.visualstudio.com/docs/copilot/customization/mcp-servers

Gemini CLI

Gemini CLI 会在每次会话中从 settings.json 读取 mcpServers：全局配置文件为 ~/.gemini/settings.json，也可以使用项目根目录中的 .gemini/settings.json，仅对该 项目生效，并且优先级更高。

gemini mcp add odoo-assistant uvx odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_DB=mycompany16-prod-12345678 \
  --scope user

展开后的相同配置：

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      },
      "timeout": 600000
    }
  }
}

timeout 是请求超时时间，单位为毫秒，默认值已经是 600000，也就是 10 分钟，因此首次调用 instance_overview 时无需修改；此处仅展示这一行，方便你在希望更快失败时调低该值。还有两个值得注意的习惯：Gemini CLI 会在启动服务前，从继承的环境变量中删除所有匹配 *KEY*、*TOKEN* 或 *SECRET* 的变量，因此必须在此 env 块中列出变量名，才能将其传入；块中的 "$MY_VAR" 则会从你的 shell 中展开。编辑后重启 CLI，再用 /mcp 检查服务。

来源：https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

来源：https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/cli-reference.md

Cline

Cline CLI 会读取 ~/.cline/mcp.json。在 IDE 扩展中，打开 Cline 面板里的 MCP Servers 图标，前往 Configure 标签页并点击 Configure MCP Servers，即可打开扩展自己的设置 JSON。两者使用相同的 mcpServers 结构：

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

请将 autoApprove 留空。它是无需询问即可运行的工具列表，而此服务中的防护机制不能替代在写入调用执行前先阅读它。cline mcp 会打开交互式向导，可在不修改文件的情况下添加、编辑、启用和移除服务。请求超时是 MCP 设置面板中的逐服务设置，而不是此文件中的键值——如果首次调用 instance_overview 超时，请在那里调高超时时间，并从同一面板重启服务。

来源：https://docs.cline.bot/mcp/mcp-overview

Roo Code

Roo Code 会读取两个文件：全局 mcp_settings.json，可通过 MCP 设置视图底部的 Edit Global MCP 按钮打开；以及针对单个项目的 .roo/mcp.json，可通过旁边的 Edit Project MCP 打开，如果文件不存在，Roo 会创建它。如果同一个服务名称同时出现在两个文件中，则使用项目中的定义。

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      },
      "alwaysAllow": [],
      "disabled": false,
      "timeout": 300
    }
  }
}

这里的 timeout 单位是秒，不是毫秒——可接受的范围是 1 到 3600，默认值为 60。60 秒足以应对除每个会话首次调用 instance_overview 之外的所有调用；应为这次调用调高超时时间。该值也对应服务面板中的 Network Timeout 下拉菜单。出于 Cline 部分所述的原因，请将 alwaysAllow 留空。编辑后，点击服务旁边的重启按钮。

提交 .roo/mcp.json 会与团队共享此服务——因此请将 API 密钥存入系统环境变量，并在 args 中使用 ${env:ODOO_API_KEY} 引用，而不要将密钥写入会纳入版本控制的文件。

来源：https://docs.roocode.com/features/mcp/using-mcp-in-roo

Zed

Zed 将其称为上下文服务，使用的键是 context_servers，而不是 mcpServers。将配置项添加到设置文件中——打开命令面板并运行 zed: open settings file——或者通过 Settings → AI → MCP Servers → Add Server → Add Local Server 让 Zed 为你写入：

{
  "context_servers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

Settings → AI → MCP Servers 中服务名称旁边的指示点会显示服务是否已启动：绿色且工具提示显示 "Server is active"，表示 Zed 已连接到该服务。工具审批由 agent.tool_permissions.default 控制，其默认值为 "confirm"；逐工具规则使用键格式 mcp:odoo-assistant:<tool_name>，例如 mcp:odoo-assistant:search_read。

来源：https://zed.dev/docs/ai/mcp

JetBrains AI Assistant

JetBrains AI Assistant 通过对话框接收配置，而不是让你自行定位配置文件。前往 Settings | Tools | AI Assistant | Model Context Protocol (MCP)，点击 Add，选择 STDIO，然后将以下内容粘贴为 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_DB": "mycompany16-prod-12345678"
      }
    }
  }
}

对话框会显示 command 和 args，并在 JSON 旁添加两个字段：Working directory 和 Server level。后者用于决定服务是全局可用，还是仅在当前项目中可用。点击 OK，然后点击 Apply——这才会实际启动服务，Status 列会显示是否已连接。如果你已在 Claude Desktop 中配置了此服务，也可以点击 Import from Claude 导入整个条目，包括其环境变量块。

来源：https://www.jetbrains.com/help/ai-assistant/mcp.html

Odoo Online 生产环境（只读示例）

如果要连接托管在 Odoo Online（SaaS）上的生产实例，必须设置 ODOO_DB，并且应将 ODOO_MCP_ALLOW 设为 "none" 以确保安全。以下是其在 Claude Desktop 中的配置示例：

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "mycompany16-prod-12345678",
        "ODOO_MCP_ALLOW": "none"
      }
    }
  }
}

设置 ODOO_DB 是绕过 Odoo Online 上已禁用的数据库列表接口的必要条件，而将 ODOO_MCP_ALLOW 设为 "none" 可确保 Agent 无法修改生产环境中的实时数据。

这些示例省略了可选变量。如果实例提供多个数据库，请设置 ODOO_DB；如果要跳过 uid 探测，请设置 ODOO_USER——登录账号，例如 [email protected]；如果门控的默认设置——允许所有方法，但拒绝的 7 个方法除外——不符合你的需求，请设置 ODOO_MCP_ALLOW / ODOO_MCP_DENY。

更新日志

每个版本的变更记录都在 CHANGELOG.md 中，而不在此处重复，以免两处内容不一致。

许可证

本项目采用 MIT License 授权。详情请参阅 LICENSE 文件。