odoo

Odoo MCP 服务

一个将 AI Agent 连接到 Odoo ERP 实例的 MCP（模型上下文协议）服务。可与 Claude Code、Cursor、Windsurf 以及任何兼容 MCP 的客户端配合使用。

支持 Odoo 17-18（JSON-RPC）和 Odoo 19+（JSON-2 API）——会自动检测最合适的协议。

快速开始

# Run directly (uv handles dependencies automatically)
ODOO_URL=https://my.odoo.com ODOO_DB=mydb ODOO_USER=admin ODOO_PASSWORD=secret \
  uv run odoo_mcp_server.py

无需 virtualenv 或 pip install——该脚本包含内联元数据，uv 会自动解析。

在 Claude Code 中配置

将以下内容添加到项目的 .mcp.json：

{
  "mcpServers": {
    "odoo": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "your-password"
      }
    }
  }
}

或者，为 Odoo 19+ 配置 API 密钥身份验证：

{
  "mcpServers": {
    "odoo": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USER": "admin",
        "ODOO_API_KEY": "your-api-key"
      }
    }
  }
}

在 Cursor / Windsurf 中配置

将以下内容添加到 ~/.cursor/mcp.json 或等效文件中：

{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "your-password"
      }
    }
  }
}

环境变量

变量	必需	说明
ODOO_URL	是	Odoo 实例 URL
ODOO_DB	是	数据库名称
ODOO_USER	是	登录用户名
ODOO_PASSWORD	以下选一	密码（Odoo 17-18）
ODOO_API_KEY	必需	API 密钥（Odoo 19+，优先使用）
ODOO_READONLY	否	设置为 true 以禁用所有写入操作

只读模式

设置 ODOO_READONLY=true 以禁用 create、update、delete 和 execute 工具。适用于安全地浏览生产实例：

{
  "mcpServers": {
    "odoo": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://production.odoo.com",
        "ODOO_DB": "prod",
        "ODOO_USER": "readonly-user",
        "ODOO_PASSWORD": "secret",
        "ODOO_READONLY": "true"
      }
    }
  }
}

可用工具

核心 CRUD

工具	说明
odoo_search_read	使用域筛选、字段选择和分页查询记录
odoo_search_count	统计匹配的记录数，无需获取数据
odoo_export	每次调用最多批量导出 2000 条记录，用于电子表格
odoo_create	创建新记录
odoo_update	按 ID 更新现有记录
odoo_delete	按 ID 删除记录
odoo_execute	运行任意模型方法（action_confirm、action_post 等）

发现

工具	说明
odoo_list_models	通过关键词筛选发现可用模型
odoo_get_fields	检查任意模型的字段定义
odoo_doctor	健康诊断（版本、模块、用户、定时任务、错误）
odoo_connection_info	显示当前连接详情

模型自定义

工具	说明
odoo_model_info	一次调用获取完整的模型元数据——字段、视图、操作、默认值、排序顺序
odoo_set_default	设置、更新或清除字段的默认值（处理 ir.default 和 JSON 编码）
odoo_get_view	获取完全渲染后的（合并）表单／树形／搜索视图 XML
odoo_modify_action	更改窗口操作的域、上下文、排序顺序、限制或视图模式

使用示例

配置完成后，可以向 AI Agent 提问：

• “列出本月的所有销售订单”
• “显示 res.partner 上的字段”
• “创建一个名为 Acme Corp 的新联系人”
• “对 Odoo 实例运行健康检查”
• “将所有产品导出到电子表格”
• “确认销售订单 42”

模型自定义示例

• “sale.order 的默认排序顺序是什么？”
• “将产品的默认发票政策改为 ‘delivery’”
• “显示 res.partner 的表单视图”
• “account.move 有哪些窗口操作？将默认排序改为 date desc”
• “列出 res.partner 上的所有自定义字段”
• “sale.order 上有哪些必填字段？”

模型自定义工具——详细参考

odoo_model_info

一次调用即可返回模型的所有信息，无需进行多次探索性查询。

odoo_model_info(model="sale.order")

返回：

• default_order — 模型的 _order 属性（例如，"date_order desc, id desc"）
• rec_name — 下拉列表中用于显示名称的字段
• field_count — 字段总数
• fields_by_type — 按类型分组的字段数量（many2one: 12, char: 8, ...）
• custom_fields — 用户创建的字段（带有 x_ 前缀或 state=manual）
• relational_fields — 所有 Many2one、One2many、Many2many 字段及其目标
• required_fields — 必须填写的字段
• views — 基础视图（表单、树形、搜索），包含 ID 和优先级
• actions — 窗口操作，包含其域、上下文和视图模式
• defaults — 为此模型的字段设置的当前 ir.default 值

odoo_set_default

通过 ir.default 管理字段默认值，并进行正确的 JSON 编码。这是 Agent 手动操作时最常见的错误来源。

# Set global default
odoo_set_default(model="product.template", field_name="invoice_policy", value="delivery")

# Set user-specific default
odoo_set_default(model="sale.order", field_name="warehouse_id", value=2, user_id=5)

# Remove a default
odoo_set_default(model="product.template", field_name="invoice_policy", value=null)

该工具：

1. 在 ir.model.fields 中查找 field_id（验证字段是否存在）
2. 自动对值进行 JSON 编码
3. 创建或更新 ir.default 记录
4. 返回更改前后的值以供确认

odoo_get_view

返回应用所有继承后的完整渲染视图 XML — 即用户实际看到的内容，而不是存储在 ir.ui.view 中的原始片段。

odoo_get_view(model="sale.order", view_type="form")
odoo_get_view(model="res.partner", view_type="tree")
odoo_get_view(model="account.move", view_type="search")

返回：

• arch — 合并后的完整 XML
• view_id — 基础视图 ID
• fields_in_view — 视图中包含的字段名称列表

odoo_modify_action

通过修改模型的窗口操作（ir.actions.act_window），更改模型在 UI 中的显示方式。

# List actions for a model (read-only)
odoo_modify_action(model="sale.order")

# Change default sort order
odoo_modify_action(action_id=42, order="date_order desc")

# Change default filter and page size
odoo_modify_action(action_id=42, domain="[['state','=','sale']]", limit=200)

# Add default grouping via context
odoo_modify_action(action_id=42, context="{'group_by': 'partner_id'}")

该工具会返回更改前后的值，方便你验证更改内容。

工作原理

AI Agent (Claude, Cursor, etc.)
    ↕ MCP Protocol (stdio)
Odoo MCP Server
    ↕ JSON-RPC / JSON-2 API
Odoo Instance

服务在启动时进行一次身份验证，并保持持久连接。所有工具都使用同一个经过身份验证的会话。

要求

• Python 3.11+
• uv（推荐）或 pip install fastmcp httpx

许可证

MIT