Odoo MCP Server Advanced

Odoo MCP服务器高级版

两种通用工具。一本成长中的烹饪书。为人工智能助手提供完整的Odoo API访问权限。

一个用于Odoo ERP的高级MCP（模型上下文协议）服务器——STDIO、SSE和流式HTTP传输——它使Claude、Cursor、ChatGPT通过MCP和其他AI主机直接访问您的Odoo数据和工作流。

AI助手： 读 代理商.md 首先快速参考工具。

______________________________________________________________________

🎯 哲学：简单与力量

通过以下方式将AI助手连接到Odoo 两种通用工具 加上自我完善的知识库：

1. execute_method --在任何模型上调用任何Odoo方法
2. batch_execute --以原子方式执行多个操作（使用 @N 结果参考）
3. add_cookbook_pattern --在≥4次失败尝试后记录来之不易的食谱

加上11个发现资源、3个提示和一个 odoo://cookbook/patterns 展示过去经验教训的资源。没有专门的工具，没有验证层，没有人为限制-完整的Odoo API。

统治他们所有人。你能做什么

你需要的一切，只需问人工智能：自动化、查询、管理、定制、开发新模块、与外部系统集成、通过人工智能增强你的Odoo实例。

______________________________________________________________________

🚀 快速开始

安装

选项1：传统pip安装

# From source
git clone https://github.com/AlanOgic/mcp-odoo-adv.git
cd mcp-odoo-adv
# Virtual Environment
python3 -m venv .venv
source .venv/bin/activate
# Installation
pip install -e .

选项2：使用uvx（无需安装）

# From source directory
uvx --from . odoo-mcp

选项3：使用Docker

# build STDIO
docker build -t alanogic/mcp-odoo-adv:latest -f Dockerfile .

# build SSE
docker build -t alanogic/mcp-odoo-adv-sse:latest -f Dockerfile.sse .

# build HTTP
docker build -t alanogic/mcp-odoo-adv-http:latest -f Dockerfile.http .

# Run STDIO
docker run --env-file .env alanogic/mcp-odoo-adv:latest

# Run SSE
docker run --env-file .env alanogic/mcp-odoo-adv-sse:latest

# Run HTTP
docker run --env-file .env alanogic/mcp-odoo-adv-http:latest

配置

创建一个 .env 文件（最小）：

cp .env.example .env
vim .env

ODOO_URL=https://your-odoo-instance.com
ODOO_DB=your-database-name
ODOO_USERNAME=your-username
ODOO_PASSWORD=your-password-or-api-key

可选：自定义配置目录

通过设置自定义目录来组织多个Odoo配置：

# Create custom config directory
export ODOO_CONFIG_DIR=~/mcp-odoo-env
mkdir -p $ODOO_CONFIG_DIR

# Copy and configure
cp .env.example $ODOO_CONFIG_DIR/.env
vim $ODOO_CONFIG_DIR/.env

# Run server (automatically uses custom directory)
odoo-mcp

这有助于：

• 管理多个Odoo实例（开发、暂存、生产）
• 组织项目目录外的配置
• Docker/Compose部署卷挂载

运行服务器

之后 pip install -e .，连接了四个控制台脚本：

# STDIO (Claude Desktop, Claude Code, Cursor)
odoo-mcp                      # or: python -m odoo_mcp

# SSE (browsers, port 8009)
odoo-mcp-sse

# Streamable HTTP (API integrations, port 8008)
odoo-mcp-http

# HTTP with Bearer auth (production behind a reverse proxy)
odoo-mcp-http-secure

每个跑步者将日志流式传输到 ./logs/mcp_server__.log 更多 stderr

Claude桌面设置

选项1：使用本地安装

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "odoo": {
      "command": "python",
      "args": ["-m", "odoo_mcp"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USERNAME": "your-username",
        "ODOO_PASSWORD": "your-password"
      }
    }
  }
}

选项2：使用uvx（推荐-无需安装）

首先，在中创建凭据 ~/.config/odoo/.env:

mkdir -p ~/.config/odoo
cat > ~/.config/odoo/.env ",
    method="",
    args_json='[...]',      # Positional arguments
    kwargs_json='{...}'     # Keyword arguments
)

示例：

# Search customers
execute_method(
    model="res.partner",
    method="search_read",
    args_json='[[["customer_rank", ">", 0]]]',
    kwargs_json='{"fields": ["name", "email"], "limit": 20}'
)

# Create sales order
execute_method(
    model="sale.order",
    method="create",
    args_json='[{"partner_id": 8, "order_line": [[0, 0, {"product_id": 5, "product_uom_qty": 1}]]}]'
)

# Confirm order
execute_method(
    model="sale.order",
    method="action_confirm",
    args_json='[[5]]'
)

2.batchexecute-原子事务

以原子方式执行多个操作。全部成功或全部回滚。使用 "@N" （1-索引）内部 args_json 以参考先前操作的结果。

batch_execute(
    operations=[
        {"model": "res.partner", "method": "create",
         "args_json": '[{"name": "Acme"}]'},
        {"model": "sale.order", "method": "create",
         "args_json": '[{"partner_id": "@1", "order_line": [[0, 0, {"product_id": 5, "product_uom_qty": 1}]]}]'},
        {"model": "sale.order", "method": "action_confirm",
         "args_json": '[[@2]]'}
    ],
    atomic=True
)

3.add_cookbook_pattern-自我完善的知识库

之后 ≥4次失败的方法 对于同一问题，记录工作解决方案，以便以后的会话跳过试错：

add_cookbook_pattern(
    problem="Search products by attribute value",
    failed_approaches=[
        "Used = on many2many field",
        "Tried dotted notation",
        "Used wrong model",
        "Passed scalar instead of list to in",
    ],
    working_solution='execute_method(model="product.template", method="search_read", args_json=\'[[["product_template_attribute_value_ids", "in", [123]]]]\')',
    why_it_works="Many2many fields require in with a list, not =",
    key_lesson="For m2m: always 'in' with a list, never '=' with scalar"
)

这 ≥4 门槛是强制执行的——肤浅的试错法不会出现在烹饪书中。

______________________________________________________________________

📚 文档

发现资源（先阅读后猜测）

加 odoo://record/{model}/{id}, odoo://search/{model}/{domain}, odoo://fields/{model}, odoo://model/{model} 用于一次性阅读。

嘻哈满汉全席

📖 COOKBOOK.md --45+实例：

• 搜索和筛选
• 创建记录
• 更新和删除
• 处理关系
• 业务工作流程
• 批量操作
• 高级图案

从这里开始！ 这本烹饪书向你展示了如何用两个工具完成任何事情。

提示

Claude菜单中的用户可选模板：

• search-customers --使用过滤器查找客户
• create-sales-order --逐步创建销售订单
• odoo-exploration --发现您的Odoo实例功能

Claude代码技能

八项技能船上 .claude/skills/ 并在Claude Code中打开此仓库时根据相关请求自动激活。他们将烹饪书包装成专注的、有触发意识的指南：

• odoo-mcp-searching --域、运算符、名称搜索
• odoo-mcp-efficient-queries --分页、字段， read_group
• odoo-mcp-crud --创建/写入/取消链接，存档与删除
• odoo-mcp-relationships --m2o/o2m/m2m命令元组
• odoo-mcp-workflows — action_confirm, action_post, button_validate
• odoo-mcp-batch --原子交易 @N 参考文献
• odoo-mcp-real-world --HR/CRM/库存跨模型配方
• odoo-mcp-learned-patterns --烹饪书读/写工作流程

其他MCP客户端（Claude Desktop、Cursor）通过以下方式可移植地获得相同的知识 COOKBOOK.md 和那个 odoo://cookbook/patterns 资源。

______________________________________________________________________

🎓 用实例学习

示例1：查找员工

execute_method(
    model="hr.employee",
    method="search_read",
    args_json='[[["name", "ilike", "john"]]]',
    kwargs_json='{"fields": ["name", "job_id", "department_id"], "limit": 10}'
)

示例2：休假请求

execute_method(
    model="hr.leave",
    method="search_read",
    args_json='[[
        ["employee_id", "=", 1],
        ["date_from", ">=", "2025-01-01"],
        ["state", "=", "validate"]
    ]]',
    kwargs_json='{"fields": ["employee_id", "date_from", "date_to", "holiday_status_id"]}'
)

示例3：创建客户+订单（原子）

batch_execute(
    operations=[
        {
            "model": "res.partner",
            "method": "create",
            "args_json": '[{"name": "Acme Corp", "email": "contact@acme.com"}]'
        },
        {
            "model": "sale.order",
            "method": "create",
            "args_json": '[{"partner_id": 123, "order_line": [[0, 0, {"product_id": 5}]]}]'
        }
    ],
    atomic=True
)

______________________________________________________________________

💡 为什么这个设计有效

✅ 主要优势

1.普及

• 完整的Odoo API触手可及
• 无人为限制
• 奥多能做什么就做什么

2.简单且可预测

• 学习2种工具，随时随地使用
• 清晰的心智模型
• 易于调试和维护

3.可靠

• Odoo提供了出色的本地错误消息
• API直接访问意味着更少的故障点
• 稳定、生产就绪的实施

4.灵活

• 适用于多个Odoo版本（14+）
• 支持所有Odoo模型和方法
• 可通过Odoo的原生功能进行扩展

______________________________________________________________________

🔥 特性

人工智能集成

• 克劳德桌面/克劳德代码/光标就绪：适用于任何MCP主机
• 通用工具: execute_method + batch_execute 达到整个Odoo API
• 自我改进食谱: odoo://cookbook/patterns 资源+ add_cookbook_pattern 工具自动增长机构知识
• 智能限制：针对超大查询的自动保护（默认值=100，最大值=1000）
• MCP 2025-06-18规格：基于FastMCP 2.12构建+

多种连接选项

• 工作室：与Claude Desktop直接集成
• 上海证券交易所：web浏览器的服务器发送事件（端口8009）
• 超文本传输协议：用于API集成的流式HTTP（端口8008）
• 码头工人：所有运输的预制集装箱

企业级就绪

• Odoo 18主要目标：通过JSON-RPC与Odoo 14-18开箱即用
• Odoo 19+选择加入：JSON-2承载令牌API可通过 ODOO_API_VERSION=json-2
• 灵活的身份验证：环境变量或配置文件
• 增强日志记录：带时间戳的登录 ./logs/
• 代理支持：HTTP代理配置
• SSL控制：可配置的SSL验证
• Python 3.10-3.13：在所有当前Python版本上进行了测试

______________________________________________________________________

🚀 高级用法

API密钥

Odoo 18（默认）： 在密码槽中使用带有API密钥的JSON-RPC路径。

export ODOO_API_VERSION=json-rpc   # default, can be omitted
export ODOO_PASSWORD=your_api_key_here

在Odoo中生成密钥： Preferences → Account Security → New API Key.

Odoo 19+（选择升级）： JSON-2承载令牌API。

export ODOO_API_VERSION=json-2
export ODOO_API_KEY=your_api_key_here

JSON-2是面向未来的——JSON-RPC计划在Odoo 20（2026年秋季）中删除。

Docker部署

# STDIO transport (Claude Desktop)
docker run -i --rm --env-file .env alanogic/mcp-odoo-adv:latest

# SSE transport (Web browsers)
docker run -p 8009:8009 --env-file .env alanogic/mcp-odoo-adv:sse

# HTTP transport (API integrations)
docker run -p 8008:8008 --env-file .env alanogic/mcp-odoo-adv:http

域名运营商

常见搜索运算符：

______________________________________________________________________

📖 文档

Odoo MCP服务器新手？ 从这里开始：

1. 用户指南.md -完整的设置指南，5分钟快速入门
2. COOKBOOK.md -45+常见任务的实例
3. 医生.md -Docker部署指南（容器、编写、生产）
4. TRANSPORTS.md -连接选项（STDIO、SSE、HTTP）
5. CLAUDE.md -技术参考和架构
6. 更改日志.md -版本历史和更新

______________________________________________________________________

🤝 贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建特征分支(git checkout -b feature/amazing)
3. 提交更改(git commit -m 'Add amazing feature')
4. 推送到分支(git push origin feature/amazing)
5. 打开拉取请求

发展理念：

• 简单第一
• 通用工具优于专用工具
• 文档过于复杂
• 通过直接实现可靠性

______________________________________________________________________

📝 许可证

GNU通用公共许可证v3.0或更高版本（GPL-3.0或更高）-请参阅 许可证 文件

此程序是自由软件：您可以根据自由软件基金会发布的GNU通用公共许可证的条款重新分发和/或修改它，无论是许可证的第3版，还是（由您选择）任何更高版本。

______________________________________________________________________

🙏 致谢

• 原始项目由 李英
• 内置于 FastMCP
• 跟随 模型上下文协议 规格

______________________________________________________________________

🎯 接下来是什么？

准备好开始了吗？

1. 快速设置：遵循 用户指南.md 5分钟快速启动
2. 范例学习：浏览 COOKBOOK.md 45+食谱
3. 探索你的Odoo：使用 odoo-exploration 克劳德提示
4. 构建和自动化：使用创建自定义工作流 execute_method

需要帮助？

• 📖 检查 用户指南.md 故障排除部分
• 💬 打开一个 问题 在GitHub上
• 🌟 如果你觉得回购有用，请为其加星！

______________________________________________________________________

将AI连接到Odoo。建设未来。 🚀