Odoo MCP Server

Odoo MCP

ERPipe 是由 erpipe-org/mcp-odoo（原名为 tuanle96/mcp-odoo）的维护者提供的托管 Odoo MCP 网关；Python 项目仍是可自托管的服务。

面向 Odoo 的免费 AI 层——适用于任何版本和版本类型。
Odoo 内置的 AI 仅限 Enterprise 版。Odoo MCP 让 Community 和 Enterprise 16+ 版免费获得同等能力，并可搭配你已在使用的大模型（Claude、GPT、Gemini、DeepSeek、Ollama）。
五分钟安装。无需在 Odoo 端进行任何设置。安全写入、真实诊断，并早在 Odoo 22 移除 XML-RPC 多年前就已支持 JSON-2。

🚀 ERPipe 托管服务 — v1 免费 · 已在 erpipe.com 上线  ·  TypeScript 开源核心  ·  🔍 固定价格审计

想通过稳定的远程 URL 使用 ChatGPT / Claude，而无需运行进程？
ERPipe 是同一作者推出的托管产品——v1 免费公开测试版，已在生产环境运行。
注册 → 添加 HTTPS Odoo 实例 → 连接一次 https://mcp.erpipe.com/mcp（工作区 OAuth、多实例、写入权限控制、审计仪表板）。
本仓库仍提供本地 / 可自托管的 Python 服务（完整的 41 个工具、stdio、Docker）。TypeScript 构建模块：erpipe。

	本仓库（odoo-mcp）	ERPipe 托管服务
运行位置	你的笔记本电脑 / Docker / CI	Cloudflare（托管）
安装	uvx odoo-mcp --setup	在 erpipe.com 注册
MCP URL	stdio 或本地 HTTP	https://mcp.erpipe.com/mcp
客户端	Claude Code、Cursor、本地 Agent	ChatGPT（主要）、Claude、Cursor、任何远程 MCP 客户端
工具范围	41 个工具 + 11 个提示词（完整本地工具包）	43 个工具 + 7 个提示词（工作区多实例 + 治理；目录）
多实例	你设备上的配置文件 / 环境变量	仪表板 + 每个工具显式指定 instance 键
写入	环境变量门控 + 审批令牌（+ 可选 MCP 询问）	默认关闭 · HITL 收件箱 · 日志 · 字段策略
审计	可选 JSONL 文件	仪表板 + D1 审计记录
费用	永久免费（MIT）	v1 免费测试版（合理使用限额）

Odoo MCP 仅使用你现有的凭据，就能将任何 Odoo 16+ 数据库变为 Model Context Protocol 服务端。**无需 App Store 模块，无需设置权限，无需管理员访问权限。**专为需要真实 Odoo 上下文的本地 Agent、IDE 和自动化工具打造，无需手写脚本或不安全的直接写入权限。 它通过 XML-RPC 与 Odoo 16-18 通信，通过 External JSON-2 与 Odoo 19+ 通信。它提供精简的 MCP 功能，包括读取工具、诊断、模式发现、迁移辅助工具、本地插件扫描，以及受限的写入工作流。一个服务可同时服务多个命名的 Odoo 实例。

30 秒快速上手

配置完成后（请参阅设置），可以向 Agent 提出以下问题：

“列出所有来自西班牙且有未付款发票的客户。”

“查找主仓库中库存低于 10 件的产品。”

“在升级到 Odoo 19 之前，审查 custom_billing 插件的升级风险。”

主要亮点

能力	提供的功能
41 个 MCP 工具	读取记录和附件、在服务端聚合、发布聊天消息、检查架构、构建域、扫描插件、诊断调用和升级日志、检查数据质量和访问规则、解析模型重命名、验证写入，以及跨实例分发查询。
字段级 ACL	可选择按实例和模型配置字段允许/拒绝规则，并在每条读取路径（记录、聚合、知识索引、资源）上强制执行。这是首个具备此功能的开源 Odoo MCP。请参阅 docs/field-acl.md。
跨实例查询	以只读方式向多个客户端数据库分发查询，并合并结果、标注来源，且容忍部分失败——无需数据仓库或同步。请参阅 docs/partner-playbook.md。
工作流提示词	11 个提示词，其中包括 6 个端到端业务工作流（发票审批、采购订单匹配、入职、费用审核、月末结账、迁移前数据质量），这些工作流会将写入操作路由到审批门控。
后台任务	submit_async_task 会在有界工作线程池中运行耗时的读取操作（插件扫描、知识索引、应收/应付账龄分析）；Agent 继续推理期间，可通过 get_async_task 轮询。
本地优先的知识搜索	index_knowledge + search_knowledge 可在有限记录范围内按 BM25 相关性排序——忽略重音符号、在进程内运行、无需嵌入服务，且数据不会离开本机。
会计工具包	receivable_payable_aging 和 accounting_health_summary 可通过一次调用回答最常见的财务问题，无需手动构建域。
Agent Skills 工具包	4 个业务工作流技能（数据质量门控、迁移助手、月末结账、代理机构车队审查）——npx skills add erpipe-org/mcp-odoo。如果你通过 shell 访问权限在 Odoo 上开发？可添加包含 21 个技能的配套开发套件 odoo-ai-skills。请参阅 skills/。
工具插件	将自有工具打包为 pip 软件包（odoo_mcp.tools 入口点）——通过 ODOO_MCP_PLUGINS 选择启用，故障隔离，无需分叉。可通过 ODOO_MCP_TOOLS_INCLUDE/EXCLUDE 按部署环境精简工具范围。请参阅 docs/plugins.md。
速率限制	可选择按实例和工具设置滑动窗口预算（ODOO_MCP_RATE_LIMIT_MODE=warn|block），并在 health_check 中显示。
多实例	一个服务支持多个命名的 Odoo 实例——每个工具均可选用 instance 参数，通过 list_instances 发现实例，审批令牌绑定实例，并按实例缓存架构。
5 个 Agent 提示词	用于失败调用、适配差距研讨会、JSON-2 迁移、安全写入和模块审计的可复用工作流。
Odoo 16-19 覆盖	默认使用 XML-RPC，Odoo 19 可选择启用 JSON-2。
MCP 2026-07-28	无状态现代协议，支持 server/discover，并能在同一端点上自动兼容旧版 2025-11-25 客户端。
Streamable HTTP	支持本地 HTTP/SSE，适用于不使用 stdio 的客户端。
智能字段选择	未提供 fields 参数时，search_records 和 read_record 会筛选与业务相关的字段——剔除审计、消息、二进制字段和未存储的计算字段等无关内容。传入 fields=["*"] 可选择退出。
服务端聚合	aggregate_records 通过 formatted_read_group（Odoo 19+）或 read_group（16-18）在 Postgres 中执行 groupby/sum/count/avg。
Chatter 集成	chatter_post 可在与写入相同的审批令牌门控下，向任何 mail.thread 记录添加消息——也可通过 MCP_CHATTER_DIRECT=1 直接添加。
区域设置配置	ODOO_LOCALE 会在每次 Odoo 调用时自动注入 context.lang（调用方可覆盖）。
结构化日志记录	可通过 ODOO_MCP_LOG_LEVEL、ODOO_MCP_LOG_JSON、ODOO_MCP_LOG_FILE 配置 JSON 格式化程序和轮转文件处理程序。
安全写入	禁止直接执行 create、write 和 unlink；已批准的写入需要实时元数据、同一会话中的令牌、明确确认以及环境门控。
人工审批	ODOO_MCP_ELICIT_WRITES=1 会在执行任何已批准的写入前显示原生 MCP 确认表单（含差异摘要）——令牌流程仍可作为后备方案。
审计跟踪	ODOO_MCP_AUDIT_LOG 会为每个写入路径事件（预览、验证、执行、chatter）追加一行 JSONL，并包含实例和令牌摘要。
弹性	只读调用在连接错误时会采用指数退避重试；架构缓存受 TTL 和 LRU 限制；health_check 会标记 N+1 读取循环。
真实冒烟测试	Docker Compose 验证会启动一次性 Odoo 16.0、17.0、18.0 和 19.0 环境，其中包括受限用户、自定义记录规则，以及打包插件 XML 的安装/更新。

为什么选择 Odoo MCP

特点	Odoo MCP	其他 MCP-Odoo 桥接工具
Odoo 端的设置步骤	0 — 使用现有凭据即可适用于任何 Odoo 16+ 实例。	通常需要安装应用商店模块、配置已启用的模型，并授予每个工具相应的权限。
安全写入工作流	审批令牌 + 实时 fields_get 验证 + 明确确认 + 环境门控。	通常直接开放 create/write/unlink，或提供“一键放行”绕过机制。
诊断	diagnose_odoo_call、diagnose_access、inspect_model_relationships、upgrade_risk_report、fit_gap_report、business_pack_report、scan_addons_source。	通常只有 CRUD。
传输方式	XML-RPC（16+）和 External JSON-2（Odoo 19+）。可提前多年应对 Odoo 22 移除 XML-RPC。	通常只有 XML-RPC — 自 Odoo 19 起已弃用，并将在 Odoo 22 中移除。
迁移辅助工具	generate_json2_payload 可在迁移前预览任意 XML-RPC 调用对应的 JSON-2 请求体。	无。
多实例	在一个配置文件中配置多个命名实例，按工具路由，各实例的令牌和缓存相互隔离。	通常每个服务进程只有一个全局连接。
Agent 提示词	提供 5 个现成提示词，用于诊断 / 差距分析 / JSON-2 迁移 / 安全写入 / 模块审计。	通常没有。
HTTP 传输安全	DNS 重绑定防护、主机/来源允许列表，默认绑定到本地。	通常缺少这些功能。
真实 Odoo 冒烟测试	Docker Compose 测试框架会为每个版本启动一次性 Odoo 16/17/18/19 环境。	通常只使用模拟测试。
框架示例	提供可直接复制粘贴的适配器，适用于 Cursor、Claude Code、OpenAI Agents、LangGraph、CrewAI 和 n8n，位于 examples/。	无。
审计与审批体验	JSONL 审计记录 + 原生 elicitation 确认表单 — 无需在 Odoo 中安装任何内容。	审计功能通常需要安装 Odoo 端模块。

在比较具体项目？请参阅 docs/comparison.md 中各项目的详细对比。

设置

有两种方式可以运行服务：自行设置，或粘贴一条提示词，让编码 Agent 帮你完成。

面向用户

最快的方式是通过 uvx 使用交互式向导，按需获取软件包：

uvx odoo-mcp --setup

向导会询问 Odoo URL、数据库和凭据，实时测试连接，写入配置文件，并输出可直接粘贴到 Claude Code、Cursor 和 Claude Desktop 中的配置片段。只想快速进行冒烟检查？运行 uvx odoo-mcp --health。

在 macOS 上使用 Claude Desktop？它会从以下位置读取 MCP 配置：

~/Library/Application Support/Claude/claude_desktop_config.json

请使用 Python 的绝对路径，因为 GUI 应用可能无法继承 shell 的 PATH：

{
  "mcpServers": {
    "odoo": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["-m", "odoo_mcp"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_DB": "your-database",
        "ODOO_USERNAME": "your-user",
        "ODOO_PASSWORD": "your-password-or-api-key",
        "ODOO_TRANSPORT": "xmlrpc"
      }
    }
  }
}

其他客户端配置（Windsurf、VS Code、Zed、Continue.dev、Streamable HTTP）请参阅 docs/client-configs.md。

其他安装方式：

pip install odoo-mcp
# or: pipx install odoo-mcp

更倾向于使用容器？请参阅 Docker。本地开发：

git clone https://github.com/erpipe-org/mcp-odoo.git
cd mcp-odoo
uv sync --extra dev

面向 AI Agent

将以下内容粘贴到 Claude Code、Cursor、Codex 或任何编码 Agent 中，它就会为你安装服务：

Install the odoo-mcp MCP server (https://github.com/erpipe-org/mcp-odoo) in this environment:

1. Ask me for my Odoo URL, database name, username, and password or API key.
   Treat them as secrets: never echo, print, or log these values.
2. Register the server as a stdio MCP server:
   - Claude Code: claude mcp add odoo --env ODOO_URL=<url> --env ODOO_DB=<db>
     --env ODOO_USERNAME=<user> --env ODOO_PASSWORD=<secret> -- uvx odoo-mcp
   - Any other client: write the equivalent config with "command": "uvx",
     "args": ["odoo-mcp"], and the same four env vars.
3. Verify the install: run `uvx odoo-mcp --health`, then call the health_check
   MCP tool and confirm the Odoo connection is reachable.
4. Leave writes disabled (do not set ODOO_MCP_ENABLE_WRITES) unless I
   explicitly ask you to enable them.

Full machine-readable instructions: https://github.com/erpipe-org/mcp-odoo/blob/main/llms-install.md

已经确定要使用的客户端？查看单行命令和配置片段：

claude mcp add odoo --env ODOO_URL=https://mycompany.odoo.com --env ODOO_DB=mycompany \
  --env [email protected] --env ODOO_PASSWORD=your-api-key -- uvx odoo-mcp

• Claude Code .mcp.json 和 Codex CLI config.toml：examples/README.md
• Cursor .cursor/mcp.json + Agent 规则：examples/cursor/
• Windsurf、VS Code、Zed、Continue.dev、Cline、Streamable HTTP、Docker：docs/client-configs.md
• 面向 Agent 的机器可读安装指南（Cline 风格）：llms-install.md

框架 SDK

可直接复制粘贴运行的集成示例位于 examples/：

客户端	示例
Cursor	examples/cursor/ — .cursor/mcp.json + Agent 规则
Claude Code / Codex CLI	examples/README.md 中的代码片段
OpenAI Agents SDK	examples/openai-agents/ — 本地版 + 托管版
LangGraph	examples/langgraph/ — langchain-mcp-adapters
CrewAI	examples/crewai/ — 使用原生 mcps=[...] 的 Agent
n8n	examples/n8n/ — 可导入的工作流 JSON

配置参考

在环境中设置连接值：

export ODOO_URL="https://your-odoo-instance.com"
export ODOO_DB="your-database"
export ODOO_USERNAME="your-user"
export ODOO_PASSWORD="your-password-or-api-key"
export ODOO_TRANSPORT="xmlrpc"

对于 Odoo 19 JSON-2：

export ODOO_TRANSPORT="json2"
export ODOO_API_KEY="your-odoo-api-key"
export ODOO_JSON2_DATABASE_HEADER="1"

ODOO_JSON2_DATABASE_HEADER=1 会在 JSON-2 调用中发送 X-Odoo-Database。只有在主机或 dbfilter 路由已选择目标数据库时，才将其设为 0。

可选环境变量：

变量	默认值	作用
ODOO_CONFIG_FILE	未设置	配置文件的显式路径，会优先于标准位置检查。
ODOO_LOCALE	未设置	在每次 Odoo 调用中注入 context.lang。调用方提供的 context.lang 始终优先。
ODOO_MCP_MAX_SMART_FIELDS	15	调用方省略 fields 时，智能字段选择的上限。
ODOO_MCP_LOG_LEVEL	INFO	进程日志记录器级别（DEBUG/INFO/WARNING/ERROR/CRITICAL）。
ODOO_MCP_LOG_JSON	0	值为真时 → 输出 JSON 格式的日志行。
ODOO_MCP_LOG_FILE	未设置	路径 → 启用轮转文件处理器（10MB × 3 个备份）。
ODOO_MCP_ENABLE_WRITES	0	使用 execute_approved_write 的必要条件。
ODOO_MCP_ALLOWED_SIDE_EFFECT_METHODS	空	精确的 model.method 允许列表（例如 sale.order.action_confirm）。
ODOO_MCP_POLICY_FILE	若存在则为 ./odoo_mcp_policy.json	可纳入版本控制并带有审核元数据的副作用允许列表（参见 odoo_mcp_policy.json.example）；与环境变量允许列表合并。
ODOO_MCP_ALLOW_UNKNOWN_METHODS	0	execute_method 的宽泛模式。建议使用上方的精确允许列表。
ODOO_MCP_AUDIT_LOG	未设置	路径 → 每个写入路径事件（预览/验证/执行/聊天）追加一行 JSONL，令牌以摘要形式存储。
ODOO_MCP_ELICIT_WRITES	0	值为真时 → execute_approved_write 会在执行前通过 MCP elicitation 向用户确认（包含差异摘要的原生确认表单）；若客户端不支持 elicitation，则回退到令牌流程。
ODOO_MCP_RETRY_ATTEMPTS	2	连接错误时只读调用的额外尝试次数（0–5）。写入操作不会重试。
ODOO_MCP_RETRY_BACKOFF	0.5	重试退避基准秒数；每次重试加倍。
ODOO_MCP_SCHEMA_CACHE_TTL	600	架构缓存条目的有效期，单位为秒。
ODOO_MCP_SCHEMA_CACHE_MAX	256	架构缓存条目上限（LRU 淘汰）。
ODOO_MCP_RATE_LIMIT_MODE	off	warn 会在 health_check 中跟踪每个 instance:tool 的调用速率；block 会拒绝超出预算的高频读取工具和 execute_method 调用。
ODOO_MCP_RATE_LIMIT_WINDOW	60	速率跟踪的滑动窗口长度，单位为秒。
ODOO_MCP_RATE_LIMIT_MAX_CALLS	120	每个 instance:tool 在每个窗口内允许的调用次数。
ODOO_MCP_ASYNC_MAX_WORKERS	2	submit_async_task 的工作线程数。
ODOO_MCP_ASYNC_MAX_TASKS	50	保留的后台任务上限（已完成的任务按从旧到新的顺序淘汰）。
ODOO_MCP_ASYNC_RESULT_TTL	3600	已完成的后台任务结果可供轮询的秒数。
ODOO_MCP_KNOWLEDGE_MAX_DOCS	5000	所有本地 BM25 知识索引合计允许的文档总数。
ODOO_MCP_FIELD_POLICY_FILE	共享策略文件	字段 ACL 策略（策略文件中的 field_acl 键，或在此处指定专用文件）。被拒绝的字段会从所有读取路径中移除。参见 docs/field-acl.md。
ODOO_MCP_CROSS_INSTANCE_WORKERS	4	跨实例扇出工具的并发上限。
MCP_CHATTER_DIRECT	0	值为真时 → chatter_post 跳过审批令牌门控，立即发布。
MCP_ALLOW_REMOTE_HTTP	0	值为真时 → 允许绑定到非本地 HTTP 地址（仍需外部身份验证/TLS）。
MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS	本地	HTTP 传输的 CSV 允许列表。
ODOO_MCP_MAX_ATTACHMENT_BYTES	1048576	read_attachment 内容的下载上限（硬上限为 16 MiB）。
ODOO_MCP_ATTACHMENT_UPLOAD_ROOTS	未设置	以冒号分隔的本地目录，validate_write 可从中读取 <field>_from_path 上传文件（与 ODOO_ADDONS_PATHS 类似）。必须设置 — 未配置根目录时会安全拒绝。
ODOO_MCP_MAX_ATTACHMENT_UPLOAD_BYTES	10485760	<field>_from_path 本地文件上传的大小上限（硬上限为 16 MiB）。
ODOO_MCP_AUTH_ISSUER_URL	未设置	OAuth 2.1：授权服务器颁发者。与下方两个变量配合使用时，HTTP 传输会成为受保护的资源服务器（RFC 9728 元数据 + bearer 验证）。
ODOO_MCP_AUTH_INTROSPECTION_URL	未设置	授权服务器的 RFC 7662 令牌内省端点。
ODOO_MCP_AUTH_RESOURCE_URL	未设置	此 MCP 服务的规范 URL（当 AS 绑定令牌时进行 RFC 8707 audience 检查）。
ODOO_MCP_AUTH_REQUIRED_SCOPES	空	每个请求都必须具备的 CSV scopes。
ODOO_MCP_AUTH_CLIENT_ID / _CLIENT_SECRET	未设置	当 AS 要求客户端身份验证时，用于内省调用的凭据。
ODOO_MCP_AUTH_REQUIRE_AUD	0	值为真时 → 拒绝内省响应中没有 aud 声明的令牌（默认仅在存在 aud 时进行检查）。
ODOO_MCP_AUTH_REQUIRE_ISS	0	值为真时 → 拒绝没有 iss 声明的内省响应。若存在 iss，则必须始终与 ODOO_MCP_AUTH_ISSUER_URL 匹配（加强防混淆攻击保护）。
ODOO_MCP_AUTH_CACHE_TTL	60	内省结果的缓存秒数（0 表示禁用）。此设置限制 AS 负载和撤销延迟。
ODOO_MCP_PLUGINS	未设置	要作为第三方工具插件加载的 CSV 入口点名称（组 odoo_mcp.tools）。仅安装不会激活任何内容；加载失败会被隔离并在 health_check 中报告。参见 docs/plugins.md。
ODOO_MCP_TOOLS_INCLUDE / _EXCLUDE	未设置	用于按部署筛选已注册工具范围的 CSV fnmatch glob（小型 Agent 会被 41 个工具淹没）。被移除的名称会在 health_check 中列出。
ODOO_MCP_INSTRUCTIONS_FILE	未设置	纯文本文件，会追加到服务器级 MCP instructions 中，并发送给每个客户端 — 用于提供部署专属指南（如财政年度规则、命名约定），而无需修改工具描述。
你也可以使用 odoo_config.json：

{
  "url": "https://your-odoo-instance.com",
  "db": "your-database",
  "username": "your-user",
  "password": "your-password-or-api-key"
}

多个 Odoo 实例

一台服务器可以连接多个 Odoo 数据库。在配置文件中添加 instances 映射（会自动检测——不含 instances 的文件仍采用上述扁平的单实例结构）：

{
  "default": "acme",
  "instances": {
    "acme": {
      "url": "https://acme.odoo.com",
      "db": "acme",
      "username": "bot",
      "api_key": "...",
      "transport": "json2"
    },
    "globex": {
      "url": "https://globex.odoo.com",
      "db": "globex",
      "username": "bot",
      "password": "...",
      "lang": "fr_FR",
      "timeout": 60
    }
  }
}

• 每个读写工具都接受可选的 instance 参数；省略时 → 使用 default 实例。若只定义了一个实例，default 本身也可以省略。
• 每个条目支持与扁平配置相同的键（url、db、username、password、api_key、transport、json2_database_header、lang），以及 timeout 和 verify_ssl。实例条目是自包含的：凭据和传输方式不会回退到环境变量（因此一个实例绝不会继承另一个部署的 ODOO_API_KEY）。只有非凭据选项（ODOO_TIMEOUT、ODOO_VERIFY_SSL、ODOO_LOCALE）会为未设置这些选项的条目提供回退默认值。像 ODOO_TRANSPORT/ODOO_API_KEY 这样的环境变量覆盖仍适用于旧版扁平配置，与之前相同。
• ODOO_CONFIG_FILE=/path/to/config.json 指定显式配置文件，查找优先级高于 ./odoo_config.json、~/.config/odoo/config.json 和 ~/.odoo_config.json。
• 优先级：当 ODOO_URL/ODOO_DB/ODOO_USERNAME/ODOO_PASSWORD 均已设置时，以环境变量为准，并定义一个名为 default 的单实例——取消设置这些变量即可使用多实例文件。
• 实例名称必须匹配 [A-Za-z0-9_-]{1,64}。客户端会延迟连接——只有工具指定某个实例时才会联系该实例。
• 发现：list_instances 工具会返回已配置的名称、URL、数据库和传输方式——绝不返回凭据。
• 写入审批令牌会编码实例名称，因此在一个实例上验证的令牌绝不会在另一个实例上执行。
• 在此版本中，MCP 资源（odoo://…）始终使用默认实例；如需访问多个实例，请使用工具。

运行

通过 stdio 启动 MCP 服务：

odoo-mcp

或者：

python -m odoo_mcp

为本地客户端启动 Streamable HTTP：

odoo-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

除非传入 --allow-remote-http 或设置 MCP_ALLOW_REMOTE_HTTP=1，否则会拒绝非本地 HTTP 绑定。此服务不包含内置 HTTP 身份验证。远程 HTTP 部署应置于你自己的身份验证、TLS 和网络策略之后。

无需启动服务循环即可检查运行时状态：

odoo-mcp --health

MCP 工具

按用例分组的 41 个工具。每个工具名称都是 Agent 可调用的单一用途句柄。配置了多个实例时，与 Odoo 通信的工具都接受可选的 instance 参数（参见多个 Odoo 实例）。

读取与发现（11）

工具	用途
list_models	列出 Odoo 模型的技术名称和标签。
get_model_fields	读取单个模型的字段元数据。
search_records	执行有界的只读 search_read。调用方未提供 fields 时，智能选择字段。
read_record	按模型和 ID 读取一条记录。调用方未提供 fields 时，智能选择字段。
aggregate_records	通过 formatted_read_group（Odoo 19+）或 read_group（16-18）在服务器端执行分组/聚合。
search_employee	按姓名搜索员工。
search_holidays	按日期范围搜索休假记录。
get_odoo_profile	读取服务器版本、用户上下文、传输方式、数据库和已安装模块摘要。
schema_catalog	构建有界的模型目录，并可选包含字段元数据。
build_domain	根据结构化条件构建并验证 Odoo 域。
read_attachment	读取 ir.attachment 的元数据和受大小限制的 base64 内容（ODOO_MCP_MAX_ATTACHMENT_BYTES，默认 1 MiB）。

写入与操作（5）

工具	用途
preview_write	为 create、write 或 unlink 生成不执行操作的审批载荷。
validate_write	根据可信的实时 fields_get 元数据验证写入载荷。
execute_approved_write	仅当 ODOO_MCP_ENABLE_WRITES=1 时，执行同一会话中经过实时验证并已确认的写入。
execute_method	执行经过审查的模型方法。禁止直接执行 create、write 和 unlink。有副作用的方法需要精确匹配允许列表，或设置 ODOO_MCP_ALLOW_UNKNOWN_METHODS=1。
chatter_post	在 mail.thread 记录上发布 chatter 消息。默认模式要求使用审批令牌预览/执行流程。

诊断（3）

工具	用途
diagnose_odoo_call	诊断模型调用，但不执行。
diagnose_access	诊断当前 Odoo 凭据的 ACL 和记录规则可见性。
inspect_model_relationships	汇总关系字段、必填字段以及创建/写入提示。

迁移（3）

工具	用途
generate_json2_payload	将 XML-RPC 格式的输入转换为 JSON-2 端点、标头和命名主体。
upgrade_risk_report	显示不同 Odoo 版本间的传输、方法和迁移风险。
lookup_model_history	根据精选的逐版本重命名目录解析过时的模型名称（account.invoice → account.move）。

审计与规划（3）

工具	用途
scan_addons_source	扫描本地插件源码，但不导入插件代码。
fit_gap_report	将需求归类为标准、配置、Studio、自定义模块、避免或未知。
business_pack_report	报告销售、CRM、库存、会计或 HR 所需的模块、模型和发现调用。

知识搜索——本地优先（3）

工具	用途
index_knowledge	获取有限范围的记录切片，并据此构建本地 BM25 索引（忽略重音符号；数据不会离开本机）。
search_knowledge	在已索引记录中进行按相关性排序的全文搜索，不会产生额外 RPC 调用。
knowledge_stats	报告各模型的索引大小和 ODOO_MCP_KNOWLEDGE_MAX_DOCS 预算。

会计（2）

工具	用途
receivable_payable_aging	按逾期天数分组的应收/应付账龄报告（未到期 / 1-30 / 31-60 / 61-90 / 90+），并显示各合作伙伴的合计。
accounting_health_summary	汇总未结应收/应付项目数量以及草稿发票积压情况。

后台任务（4）

工具	用途
submit_async_task	在有限的工作线程池中运行允许列表内的长时间读取操作（scan_addons_source、index_knowledge、receivable_payable_aging）。不接受写入操作。
get_async_task	查询任务状态和结果。
cancel_async_task	取消待处理或正在运行的任务。
list_async_tasks	列出正在运行和最近完成的任务。

跨实例扇出——只读（3）

在多个已配置实例间查询同一个问题，合并结果并标注来源。参见合作伙伴操作手册。

工具	用途
search_across_instances	搜索每个已选择加入的实例（或指定的列表/标签）；行中会标记 _instance，单个实例失败时仍返回部分结果。
aggregate_across_instances	按实例分组/汇总，并计算整个实例群的可加总总计。
accounting_health_across_instances	汇总每个客户端数据库的应收/应付账龄及合并分组——合作伙伴网络扫描。

实用工具（2）

工具	用途
health_check	报告非敏感的 MCP 运行状态，包括启用时的速率限制计数器和字段 ACL 状态。
list_instances	列出已配置的 Odoo 实例名称、URL、数据库、传输方式和跨实例标签——绝不包含凭据。

资源

URI	描述
odoo://models	列出可用模型。
odoo://model/{model_name}	读取模型元数据和字段。
odoo://record/{model_name}/{record_id}	读取一条记录。
odoo://search/{model_name}/{domain}	使用受限域搜索记录。

提示词

共有 11 个提示词：5 个诊断提示词，以及 6 个操作型工作流提示词，用于编码端到端业务流程，并确保每次写入都经过审批关卡。

提示词	用途
diagnose_failed_odoo_call	在重试之前，找出 Odoo 调用失败的根本原因。
fit_gap_workshop	将原始需求归入 Odoo 适配/差距类别。
json2_migration_plan	规划从 XML-RPC 或 JSON-RPC 迁移到 External JSON-2。
safe_write_review	审查拟执行的 create、write 或 unlink。
custom_module_audit	使用扫描、风险和业务证据审计本地附加模块源代码。
invoice_approval_chain	分类处理草稿发票，并通过写入关卡和人工检查点逐一过账。
po_to_receipt	对采购订单、收货单和账单进行三方匹配；标记差异（只读）。
customer_onboarding	检查重复项，然后通过关卡创建客户及其联系人和付款条款。
expense_claim_review	检查待处理报销申请是否符合政策，然后通过关卡批准或拒绝。
accounting_close_checklist	只读月末检查清单：账龄、未对账项目、草稿积压。

安全写入模型

写入流程刻意保持简单。

1. preview_write 创建规范化的非执行载荷。
2. validate_write 检查模型元数据、必填字段、只读字段、关系提示、记录 ID 和载荷结构。
3. 只有在所有关卡均通过时，execute_approved_write 才会执行：
   • 审批来自同一服务进程中的 validate_write，
   • 验证使用了可信、非空且实时获取的 Odoo fields_get 元数据，
   • 令牌尚未过期或被使用，
   • 已传入 confirm=true，
   • 已设置 ODOO_MCP_ENABLE_WRITES=1。

最终结果仍由 Odoo 访问规则、记录规则和服务端约束决定。

批量创建也需经过同样的关卡：将 values_list（每条记录一个字典，最多 100 条）传给 preview_write/validate_write——执行时会映射为一次原子 Odoo create(vals_list) 调用。刻意不支持每条记录使用不同 write 值（这需要对每条记录进行一次非原子 RPC）。可选附加功能：ODOO_MCP_ELICIT_WRITES=1 会添加原生人工确认表单，ODOO_MCP_AUDIT_LOG 会记录写入路径中的每个事件。

大型二进制字段（例如附加在 ir.attachment.datas 上的简历、产品图片等）不必以 base64 内联到工具调用中——改为传入 <field>_from_path（例如 datas_from_path: "/local/path/cv.pdf"）并传给 validate_write。服务会自行读取文件；审批中对此字段始终只包含 sha256:<hex>:<size> 指纹，不会包含实际内容，因此无需通过调用 Agent 的上下文来回传输大型内容。需要设置 ODOO_MCP_ATTACHMENT_UPLOAD_ROOTS（否则会拒绝操作），并遵守 ODOO_MCP_MAX_ATTACHMENT_UPLOAD_BYTES 的限制。无需新增工具——此流程与其他所有写入一样，经过 preview_write → validate_write → execute_approved_write 关卡。

可以逐个启用经过审查的副作用方法，例如 sale.order.action_confirm：

export ODOO_MCP_ALLOWED_SIDE_EFFECT_METHODS="sale.order.action_confirm,res.partner.message_post"

可信部署仍支持 ODOO_MCP_ALLOW_UNKNOWN_METHODS=1，但 health_check 会将其报告为宽泛模式。如果只需要少数经过审查的方法，请优先使用精确的允许列表条目。

Docker

使用预构建的 GHCR 镜像：

docker pull ghcr.io/erpipe-org/mcp-odoo:latest

或在本地构建：

docker build -t mcp/odoo:latest -f Dockerfile .

通过 MCP 客户端使用 stdio 运行（将 mcp/odoo:latest 替换为 ghcr.io/erpipe-org/mcp-odoo:latest 即可使用预构建镜像）：

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "ODOO_URL",
        "-e", "ODOO_DB",
        "-e", "ODOO_USERNAME",
        "-e", "ODOO_PASSWORD",
        "-e", "ODOO_TRANSPORT",
        "-e", "ODOO_API_KEY",
        "mcp/odoo:latest"
      ]
    }
  }
}

在本地运行 Streamable HTTP：

docker run --rm \
  -p 127.0.0.1:8000:8000 \
  -e ODOO_URL \
  -e ODOO_DB \
  -e ODOO_USERNAME \
  -e ODOO_PASSWORD \
  -e ODOO_TRANSPORT \
  -e ODOO_API_KEY \
  mcp/odoo:latest \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --allow-remote-http

测试

运行常规质量检查：

uv run python -m ruff check .
uv run python -m mypy src
uv run python -m pytest

运行真实的 Odoo 冒烟测试：

uv run --python 3.12 --with-editable . scripts/odoo_compose_smoke.py \
  --versions 16.0 17.0 18.0 19.0 \
  --timeout 360 \
  --inspector-smoke

冒烟测试框架会启动一次性 Docker Compose 堆栈，验证直接访问 Odoo、MCP 标准输入/输出，并在 Odoo 19 中验证 JSON-2 和 Streamable HTTP。

运行多实例冒烟测试（一个堆栈、三个数据库、同一实例上的两个账户）：

uv run --python 3.12 --with-editable . scripts/odoo_multi_instance_smoke.py

兼容性

为广泛兼容，XML-RPC 仍是默认传输方式。Odoo 19 支持通过 ODOO_TRANSPORT=json2 使用 External JSON-2。XML-RPC 和 JSON-RPC 自 Odoo 19 起已弃用，并计划于 Odoo 22（2028 年秋季）移除，因此新的集成应规划迁移至 JSON-2。

文档

指南	内容
docs/comparison.md	Odoo MCP 与其他 Odoo MCP 桥接工具的比较
docs/architecture.md	系统结构、传输方式、安全边界
docs/multi-instance.md	多数据库配置、路由、隔离模型
docs/troubleshooting.md	从错误文本定位根本原因（ACL、记录规则、路由）
docs/performance.md	缓存/重试参数、批处理模式、N+1 检测
docs/client-configs.md	Claude Desktop、Docker、Streamable HTTP 设置
docs/testing.md	本地检查和 Docker Compose 冒烟测试框架

贡献

欢迎提交问题、拉取请求和兼容性报告。请从 CONTRIBUTING.md 开始，并注明 Odoo 版本、传输方式、客户端类型以及你运行的验证。

安全

请勿公开包含 Odoo 凭据、API 密钥、私人环境中的数据库名称或完整 Odoo 调试跟踪的日志。请通过 SECURITY.md 报告漏洞。

许可证

MIT。请参阅 LICENSE。