Odoo 19 MCP服务器
模型上下文协议（MCP）服务器，提供与Odoo19的外部JSON-2 API交互的工具。此服务器使Claude和其他MCP客户端能够在Odoo数据库上执行CRUD操作和查询。
特性
- 多公司支持：从单个MCP服务器管理多个Odoo实例/公司
- 完整的CRUD操作：创建、读取、更新和删除记录
- 高级搜索：使用复杂的域筛选器进行搜索
- 批量操作：对多条记录执行操作
- 图像处理：内置支持使用Pillow处理图像（调整大小、格式转换）
- 稳健的错误处理：针对瞬态故障，采用指数回退自动重试
- 连接池：高效的HTTP连接重用，以获得更好的性能
- 可配置超时：防止挂在缓慢/无响应的服务器上
- 类型安全：正确的输入验证和错误处理
- Docker支持：多阶段构建，优化图像大小和安全性
- 生产就绪：非root用户、健康检查和全面日志记录
可用工具
1. odoo_list_companies
列出所有可用的公司配置。
参数： 无
退货： 已配置的公司名称列表
2. odoo_search_read
搜索并读取Odoo模型的记录。
参数：
company（必填）：公司配置名称（来自.env部分）model（必填）：Odoo型号名称（例如。，res.partner,account.move)domain（可选）：以列表形式搜索条件（例如。，[["name", "=", "John"]])fields（可选）：要检索的字段名列表limit（可选）：最大记录数offset（可选）：要跳过的记录数order（可选）：排序顺序（例如。，"name asc")
3. odoo_create
在Odoo模型中创建新记录。
参数：
company（必填）：公司配置名称model（必填）：Odoo型号名称values（必填）：字段值字典
4. odoo_write
更新现有记录。
参数：
company（必填）：公司配置名称model（必填）：Odoo型号名称ids（必填）：要更新的记录ID列表values（必填）：要更新的字段值字典
5. odoo_unlink
从Odoo模型中删除记录。
参数：
company（必填）：公司配置名称model（必填）：Odoo型号名称ids（必填）：要删除的记录ID列表
6. odoo_search
在不读取完整记录的情况下搜索记录ID。
参数：
company（必填）：公司配置名称model（必填）：Odoo型号名称domain（可选）：搜索条件limit,offset,order（可选）：与search_read相同
7. odoo_read
通过ID读取特定记录。
参数：
company（必填）：公司配置名称model（必填）：Odoo型号名称ids（必填）：记录ID列表fields（可选）：要检索的字段名列表
8. odoo_search_count
统计符合搜索条件的记录。
参数：
company（必填）：公司配置名称model（必填）：Odoo型号名称domain（可选）：搜索条件
先决条件
- Python 3.10或更高版本（用于本地开发）
- Docker和Docker Compose（用于容器化部署）
- 启用了外部API的Odoo 19实例
- Odoo API密钥（请参阅配置部分）
配置
获取Odoo API密钥
- 登录您的Odoo实例
- 首选 设置 → 用户和公司 → 用户
- 选择您的用户
- 转到 偏好设置 标签
- 在 API密钥 部分，单击 新API密钥
- 给它一个描述，然后单击 生成
- 复制生成的API密钥（只显示一次）
多公司配置
服务器支持通过单个MCP服务器实例管理多个Odoo实例/公司。每个公司都配置在 .env 使用INI样式节的文件。
创建一个 .env 项目根目录中的文件：
cp .env.example .env编辑 .env 根据您的公司配置：
# Company 1
[company1]
ODOO_URL=http://localhost:8069
ODOO_DATABASE=database_name
ODOO_API_KEY=your_api_key_here
COMPANY_ID=1 # Optional, defaults to 1
# Company 2 - same database, different company
[company2]
ODOO_URL=http://localhost:8069
ODOO_DATABASE=database_name
ODOO_API_KEY=another_api_key
COMPANY_ID=2
# Company 3 - different database
[production]
ODOO_URL=https://instance.odoo.com
ODOO_DATABASE=production_db
ODOO_API_KEY=production_key
COMPANY_ID=1要点：
- 每
[section_name]定义公司配置 - 节名称用作
company工具调用中的参数 - 多家公司可以使用不同的API密钥连接到同一Odoo实例/数据库
COMPANY_ID是可选的，如果未指定，则默认为1
高级配置
您可以使用环境变量配置请求行为：
[company1]
ODOO_URL=http://localhost:8069
ODOO_DATABASE=database_name
ODOO_API_KEY=your_api_key_here
COMPANY_ID=1
# Optional: Override global settings per company
ODOO_REQUEST_TIMEOUT=30 # Request timeout in seconds (default: 30)
ODOO_MAX_RETRIES=3 # Maximum retry attempts (default: 3)或者在您的环境中设置全局默认值/docker-compose：
# docker-compose.yml
environment:
- ODOO_REQUEST_TIMEOUT=60 # Longer timeout for slow networks
- ODOO_MAX_RETRIES=5 # More retries for unreliable connections性能调整：
- 降低
ODOO_REQUEST_TIMEOUT用于更快地检测不良连接的故障 - 增加
ODOO_MAX_RETRIES对于不可靠的网络（建议最大值：5） - 重试使用指数回退：两次尝试之间等待1秒、2秒、4秒
安装与使用
选项1:Docker（推荐）
- 使用Docker Compose构建和运行：
docker-compose up -d- 查看日志：
docker-compose logs -f- 停止服务器：
docker-compose down方案2：地方发展
- 创建虚拟环境：
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项：
pip install -r requirements.txt- 运行服务器：
python src/odoo_mcp_server.py与Claude Desktop一起使用
快速设置（推荐）
运行自动安装脚本：
./setup-claude-desktop.sh此脚本将：
- 构建Docker镜像
- 验证Docker是否正在运行
- 向您显示要添加到Claude Desktop的确切配置
手动设置
有关详细说明，包括故障排除和高级配置，请参阅 CLAUDE_DESKTOP_SETUP.md.
配置文件位置：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%/Claude/claude_desktop_config.json - Linux：
~/.config/Claude/claude_desktop_config.json
Docker安装程序（推荐）：
{
"mcpServers": {
"odoo": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--env-file",
"/absolute/path/to/claude-odoo-api/.env",
"odoo-mcp-server"
]
}
}
}本地Python设置：
{
"mcpServers": {
"odoo": {
"command": "python",
"args": [
"/absolute/path/to/claude-odoo-api/src/odoo_mcp_server.py"
],
"env": {
"ODOO_CONFIG_FILE": "/absolute/path/to/claude-odoo-api/.env"
}
}
}
}重要提示：
- 用实际的绝对路径替换路径
- 如果您的Odoo位于本地主机上，请使用
host.docker.internal在.env或添加"--network", "host"到Docker参数 - 更新配置后，完全重新启动Claude Desktop
看 CLAUDE_DESKTOP_SETUP.md 有关完整的设置说明和故障排除。
示例和脚本
看看 examples/ 即用型脚本目录：
process_contact_images.py：通过自动调整大小和生成HTML库导出和处理联系人图像
python examples/process_contact_images.py看 示例/README.md 查看详细文档和更多示例。
示例用法
连接后，您可以要求Claude与您的Odoo实例进行交互：
列出可用公司：
List all available Odoo companies寻找合作伙伴：
Find all partners with 'John' in their name in company1创建新合作伙伴：
Create a new partner in company2 with name "Acme Corp" and email "contact@acme.com"更新记录：
Update partner ID 42 in production to set their phone to "555-1234"计数记录：
How many invoices do we have in draft status in company1?复杂查询：
Find all sales orders in company2 created in the last 30 days with a total amount greater than $1000多公司运营：
Compare the number of active customers between company1 and company2Odoo域语法
Odoo使用域过滤器语法进行搜索。以下是一些常见的例子：
# Equals
[["name", "=", "John"]]
# Not equals
[["state", "!=", "draft"]]
# Greater than / Less than
[["amount_total", ">", 1000]]
# In list
[["state", "in", ["sale", "done"]]]
# Like (contains)
[["name", "ilike", "john"]] # case-insensitive
# AND conditions (default)
[["name", "=", "John"], ["city", "=", "New York"]]
# OR conditions
["|", ["name", "=", "John"], ["name", "=", "Jane"]]
# Complex nested conditions
["|", ["state", "=", "draft"], "&", ["amount_total", ">", 1000], ["partner_id", "!=", False]]常见Odoo型号
res.partner-客户、供应商、联系人product.product-产品中心product.template-产品模板sale.order-销售订单sale.order.line-销售订单行account.move-发票、账单、日记账分录account.move.line-发票/账单行stock.picking-仓库转移purchase.order-采购订单project.project-项目project.task-任务hr.employee-员工crm.lead-CRM线索/机会
故障排除
连接问题
- 验证Odoo是否可访问：
curl http://your-odoo-url:8069/web/database/selector- 测试API密钥验证：
curl -X POST http://your-odoo-url:8069/json/2/res.partner/search_count \
-H "Authorization: Bearer your_api_key" \
-H "X-Odoo-Database: your_database" \
-H "Content-Type: application/json" \
-d '{"domain": []}'Docker网络问题
如果在本地运行Odoo，而容器无法访问它，请使用 host.docker.internal 而不是 localhost:
ODOO_URL=http://host.docker.internal:8069或者使用主机网络：
docker run --network host ...API访问被拒绝
确保Odoo计划支持外部API。根据Odoo文件：
- 外部API访问需要自定义Odoo定价计划
- 不适用于One App免费或标准计划
测试
该项目包括全面的单元测试。
在本地运行测试
- 安装测试依赖项：
pip install -r requirements.txt- 运行所有测试：
pytest tests/ -v- 运行覆盖率报告：
pytest tests/ -v --cov=src --cov-report=html- 查看覆盖率报告：
open htmlcov/index.html # macOS
# or
xdg-open htmlcov/index.html # Linux持续集成
该项目使用GitHub Actions for CI/CD：
- 测试：在Python 3.10、3.11和3.12上运行
- 代码检查：使用flake8、黑色和isort进行代码样式检查
- 码头工人：自动构建Docker镜像
看 .github/workflows/ci.yml 有关工作流的详细信息。
发展
项目结构
claude-odoo-api/
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI/CD workflow
├── src/
│ └── odoo_mcp_server.py # Main MCP server implementation
├── tests/
│ ├── __init__.py
│ ├── test_odoo_mcp_server.py # Unit tests
│ └── README.md # Test documentation
├── Dockerfile # Docker image definition
├── docker-compose.yml # Docker Compose configuration
├── requirements.txt # Python dependencies (includes test deps)
├── pytest.ini # Pytest configuration
├── pyproject.toml # Python project metadata
├── .env.example # Environment variables template
├── .gitignore # Git ignore rules
├── CLAUDE.md # Developer documentation
├── README.md # This file
└── create_odoo_invoices.py # Example usage script添加新工具
添加新的Odoo API操作：
- 向添加方法
OdooClient类（如果需要） - 在中添加工具定义
list_tools()
- 包含 company 作为Odoo操作的必需参数
- 在中添加工具处理程序
call_tool()
- 提取公司参数并获取客户端实例
- 在中添加相应的单元测试
tests/
看 CLAUDE.md 获取详细的实施指南。
资源
许可证
麻省理工学院
贡献
欢迎投稿！请随时提交拉取请求。