Odoo MCP

Odoo MCP 将 Odoo 数据库转换为模型上下文协议（MCP）服务器。它专为需要真实 Odoo 上下文，但又不想使用手动脚本或不安全直接写入访问的本地代理、IDE 和自动化工具而构建。

它支持 Odoo 16-18 的 XML-RPC 和 Odoo 19 的外部 JSON-2。它暴露了一个紧凑的 MCP 界面，包含读取工具、诊断、模式发现、迁移助手、本地插件扫描以及受控的写入工作流。

亮点

功能	提供的价值
22 个 MCP 工具	读取记录、检查模式、构建域、扫描插件、诊断调用、访问规则和验证写入。
5 个代理提示词	用于失败调用、适配/差距分析研讨会、JSON-2 迁移、安全写入和模块审计的可重用工作流。
Odoo 16-19 覆盖	默认使用 XML-RPC，Odoo 19 可选 JSON-2。
流式 HTTP	为不使用 stdio 的客户端提供本地 HTTP/SSE 支持。
安全写入	直接的 `create`、`write` 和 `unlink` 被拦截；批准的写入需要实时元数据、同会话令牌、明确确认和环境门控。
真实冒烟测试	Docker Compose 验证会启动一次性的 Odoo 16.0、17.0、18.0 和 19.0 堆栈，包括受限用户、自定义记录规则以及打包的插件 XML 安装/更新。

Related MCP server: Odoo MCP Server

安装

pip install odoo-mcp

对于本地开发：

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

配置

在环境中设置连接值：

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.json：

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

运行

通过 stdio 启动 MCP 服务器：

odoo-mcp

或者：

python -m odoo_mcp

为本地客户端启动流式 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 工具

工具	用途
`execute_method`	执行经过审查的模型方法。直接的 `create`、`write` 和 `unlink` 被拦截。副作用方法需要精确的允许列表或设置 `ODOO_MCP_ALLOW_UNKNOWN_METHODS=1`。
`list_models`	列出 Odoo 模型技术名称和标签。
`get_model_fields`	读取一个模型的字段元数据。
`search_records`	运行受限的只读 `search_read`。
`read_record`	按模型和 ID 读取一条记录。
`search_employee`	按名称搜索员工。
`search_holidays`	按日期范围搜索请假记录。
`diagnose_odoo_call`	在不执行的情况下诊断模型调用。
`diagnose_access`	为当前 Odoo 凭据诊断 ACL 和记录规则可见性。
`inspect_model_relationships`	分组关系字段、必填字段和创建/写入提示。
`generate_json2_payload`	将 XML-RPC 格式的输入转换为 JSON-2 端点、标头和命名主体。
`upgrade_risk_report`	揭示跨 Odoo 版本的传输、方法和迁移风险。
`fit_gap_report`	将需求分类为标准、配置、Studio、自定义模块、避免或未知。
`get_odoo_profile`	读取服务器版本、用户上下文、传输、数据库和已安装模块摘要。
`schema_catalog`	构建一个带有可选字段元数据的受限模型目录。
`preview_write`	为 `create`、`write` 或 `unlink` 生成非执行的批准载荷。
`validate_write`	根据受信任的实时 `fields_get` 元数据验证写入载荷。
`execute_approved_write`	仅在 `ODOO_MCP_ENABLE_WRITES=1` 时执行经过同会话、实时验证且确认的写入。
`scan_addons_source`	在不导入插件代码的情况下扫描本地插件源码。
`build_domain`	从结构化条件构建并验证 Odoo 域。
`business_pack_report`	报告销售、CRM、库存、会计或人力资源的预期模块、模型和发现调用。
`health_check`	报告非机密的 MCP 运行时状态。

资源

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

提示词

提示词	用途
`diagnose_failed_odoo_call`	在重试前对失败的 Odoo 调用进行根本原因分析。
`fit_gap_workshop`	将原始需求转化为 Odoo 适配/差距分析桶。
`json2_migration_plan`	规划从 XML-RPC 或 JSON-RPC 到外部 JSON-2 的迁移。
`safe_write_review`	审查提议的 `create`、`write` 或 `unlink` 操作。
`custom_module_audit`	通过扫描、风险和业务证据审计本地插件源码。

安全写入模型

写入操作被刻意设计得非常严谨。

preview_write 创建一个规范的、非执行的载荷。
validate_write 检查模型元数据、必填字段、只读字段、关系提示、记录 ID 和载荷形状。
execute_approved_write 仅在所有门控通过时运行：
- 批准来自同一服务器进程中的 validate_write，
- 验证使用了受信任的、非空的实时 Odoo fields_get 元数据，
- 令牌未过期或未被消耗，
- 传递了 confirm=true，
- 设置了 ODOO_MCP_ENABLE_WRITES=1。

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

经过审查的副作用方法（如 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 会将其报告为广泛模式。当你只需要少量经过审查的方法时，请优先使用精确的允许列表条目。

客户端设置

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"
      }
    }
  }
}

更多示例请参见 docs/client-configs.md。

Docker

构建镜像：

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

从 MCP 客户端通过 stdio 运行：

{
  "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"
      ]
    }
  }
}

在本地运行流式 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 stdio，对于 Odoo 19，还会验证 JSON-2 和流式 HTTP。

兼容性

XML-RPC 仍然是广泛兼容性的默认传输方式。Odoo 19 通过 ODOO_TRANSPORT=json2 支持外部 JSON-2。Odoo 已记录了针对 Odoo 20 的 XML-RPC 和 JSON-RPC 弃用计划，因此新的集成应规划使用 JSON-2。

贡献

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

安全

不要发布包含 Odoo 凭据、API 密钥、私有环境数据库名称或完整 Odoo 调试跟踪的日志。请通过 SECURITY.md 报告漏洞。

许可证

MIT。请参阅 LICENSE。

Odoo MCP Server

Odoo MCP

亮点

安装

配置

运行

MCP 工具

资源

提示词

安全写入模型

客户端设置

Docker

测试

兼容性

贡献

安全

许可证

Maintenance

Resources

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API