odoo-mcp

OdooClaw MCP

适用于 Odoo 18、通过 stdio 运行的独立 MCP（Model Context Protocol）服务。

MCP 名称： io.github.nicolasramos/odooclaw-mcp
PyPI 包： odooclaw-mcp
官方 CLI： odooclaw-mcp

同时也会安装向后兼容的别名：

• odoo-mcp
• odoo-mcp-server
• odoo-18-mcp-server

快速开始

1) 安装

pip install odooclaw-mcp

从源码安装：

git clone https://github.com/nicolasramos/odooclaw-mcp.git
cd odooclaw-mcp
pip install -e .

2) 配置环境

cp .env.example .env

必需项：

ODOO_URL=https://yourcompany.odoo.com
ODOO_DB=your_database
ODOO_USERNAME=your_username
ODOO_PASSWORD=your_password

可选项：

ODOO_MCP_DEFAULT_LIMIT=50
ODOO_MCP_MAX_LIMIT=80
LOG_LEVEL=INFO

3) 验证并运行

odooclaw-mcp --check-config
odooclaw-mcp

替代方式：

python -m odoo_mcp

MCP 客户端配置（stdio）

{
  "mcpServers": {
    "odoo": {
      "command": "odooclaw-mcp",
      "env": {
        "ODOO_URL": "https://yourcompany.odoo.com",
        "ODOO_DB": "your_database",
        "ODOO_USERNAME": "your_username",
        "ODOO_PASSWORD": "your_password",
        "ODOO_MCP_DEFAULT_LIMIT": "50",
        "ODOO_MCP_MAX_LIMIT": "80"
      }
    }
  }
}

工具调用负载约定

通过 MCP 协议调用工具时，参数必须封装在顶层的 payload 对象中。

有效格式：

{
  "name": "odoo_search",
  "arguments": {
    "payload": {
      "model": "res.partner",
      "domain": [["customer_rank", ">", 0]],
      "limit": 3
    }
  }
}

如果省略 payload，验证会失败，并返回类似 Field required: payload 的错误。

范围

• 129 个用于 Odoo 操作的 MCP 工具（CRUD + 业务操作 + 迁移工作流）
• 对所有工具负载进行 Pydantic 验证
• Odoo 18 兼容性辅助工具（customer_rank / supplier_rank / payment_state）
• 安全防护措施（模型允许列表、禁止字段列表、操作防护、禁用 unlink）
• 结构化日志记录和审计操作

可用工具

该服务目前提供 129 个 MCP 工具。

注意：下方的分组表格重点介绍常用且价值较高的工具。请使用 MCP list_tools 查看已安装版本的完整实时工具目录。

核心记录操作

工具	用途
odoo_search	使用 Odoo 域语法搜索允许的模型中的记录。
odoo_read	从指定记录 ID 读取选定字段。
odoo_search_read	合并搜索和读取，高效获取数据。
odoo_create	在允许的模型中创建新记录。
odoo_write	更新允许的模型中的现有记录。
odoo_invoke_action	调用 Odoo 模型方法，例如 action_* 或 button_*。
odoo_get_record_summary	返回简洁易读的记录摘要。

合作伙伴、销售和 CRM

工具	用途
odoo_find_partner	按名称、VAT 或电子邮件查找客户或供应商。
odoo_get_partner_summary	获取合作伙伴概览及实用的业务背景信息。
odoo_find_sale_order	按名称、合作伙伴或状态搜索销售订单。
odoo_get_sale_order_summary	获取包含订单行的销售订单摘要。
odoo_create_sale_order	创建包含产品行的报价单 / 销售订单。
odoo_confirm_sale_order	将报价单确认为销售订单。
odoo_create_lead	创建 CRM 线索 / 商机。

会计、采购和付款

工具	用途
odoo_create_purchase_order	根据合作伙伴和订单行数据创建采购订单。
odoo_create_vendor_invoice	创建供应商账单。
odoo_find_pending_invoices	按照 Odoo 18 的语义查找已过账且待付款的发票或账单。
odoo_get_invoice_summary	获取发票或账单的详细摘要。
odoo_register_payment	为指定发票登记付款。

项目、活动和 chatter

工具	用途
odoo_find_task	按名称、项目或阶段搜索项目任务。
odoo_create_task	创建新的项目任务。
odoo_update_task	更新任务阶段、负责人或截止日期。
odoo_create_activity	在记录上安排活动。
odoo_list_pending_activities	列出待处理的活动，可按模型或负责人筛选。
odoo_mark_activity_done	将活动标记为已完成。
odoo_post_chatter_message	在记录上发布 chatter 消息。
odoo_create_activity_summary	创建摘要式活动以供后续跟进。
odoo_close_activity_with_reason	关闭活动并记录原因。
odoo_log_timesheet	为项目或任务记录工时表条目。

支持、合同、库存和实例功能

工具	用途
odoo_get_capabilities	报告已连接实例中可用的模块和功能。
odoo_create_helpdesk_ticket	直接创建帮助台工单。
odoo_create_helpdesk_ticket_from_partner	创建关联到合作伙伴的帮助台工单。
odoo_draft_ticket_email	根据工单上下文准备支持邮件草稿。
odoo_create_contract_line	向合同添加一行。
odoo_replace_contract_line	用新行替换现有合同条目。
odoo_close_contract_line	根据原因和关闭日期关闭合同条目。
odoo_get_product_stock	查看产品的库存数量。
odoo_create_calendar_event	创建包含参会者的会议或预约。

自省

工具	用途
odoo_get_model_schema	查看模型的字段和架构，例如 res.partner 或 account.move。

可用资源

该服务还公开了 5 个 MCP 资源，用于发现和获取上下文：

资源	用途
odoo://context/odoo18-fields-reference	Odoo 18 字段参考，涵盖 customer_rank、supplier_rank 和 payment_state 等常见模型／域问题。
odoo://models	当前受安全策略允许的模型 JSON 列表。
odoo://model/{model_name}/schema	特定 Odoo 模型的技术架构。
odoo://record/{model}/{id}/summary	特定记录的 JSON 摘要。
odoo://record/{model}/{id}/chatter_summary	特定记录的聊天记录摘要。

防护措施和运行时行为

• 使用标准 Odoo JSON-RPC 端点；不依赖 OdooClaw 委派。
• 工具负载在执行前使用 Pydantic 进行验证。
• 模型访问受服务配置中定义的允许列表限制。
• 敏感写入字段列入拒绝列表，且禁用 unlink。
• 搜索类工具使用默认和最大限制（ODOO_MCP_DEFAULT_LIMIT、ODOO_MCP_MAX_LIMIT）。
• sender_id 被视为审计／上下文元数据；操作以经过身份验证的 Odoo 会话用户身份执行。
• 部分工具需要安装相应的 Odoo 应用／模块（CRM、Helpdesk、Projects、Contracts、Inventory 等）。

安全模型

该服务使用标准 Odoo JSON-RPC 端点，并以配置的 Odoo 会话用户身份执行操作。

在生产环境中，请使用专用的最小权限 Odoo 账户。

生产环境说明

• 这是一个 stdio MCP 服务，而非 HTTP API 服务。
• Docker／Compose 支持主要用于打包或受控运行场景。
• 在常规用法中，MCP 客户端会直接启动服务进程。
• 请将 Odoo 凭据保存在环境变量或密钥管理器中。

已知限制

• 每个 MCP 进程仅支持一个 Odoo 凭据上下文。
• 身份验证流程目前要求设置 ODOO_DB。
• 部分工具需要特定的 Odoo 应用／模块（CRM、Helpdesk、Project 等）。
• 针对 Odoo 18 字段语义设计。

开发

pip install -e .[dev]
ruff check src tests
black --check src tests
mypy src --ignore-missing-imports
pytest tests -v
python -m build
twine check dist/*

文档

• 架构
• 部署
• QA 运行手册

许可证

MIT - 详见 LICENSE。