内容
# odoo-fast-mcp
使用OdooRPC的Odoo 16+模型上下文协议（MCP）服务器。此服务器通过标准化的接口使AI助手能够与Odoo ERP系统交互。
## 功能 🚀
- **完整的CRUD操作**：在任何Odoo模型中创建、读取、更新、删除记录
- **连接管理**：连接到多个数据库，自动从配置连接
- **模型自省**：发现模型和字段定义
- **方法执行**：调用任何Odoo模型方法（工作流操作，自定义方法）
- **报告生成**：生成和下载Odoo报告（PDF）
- **MCP资源**：访问连接状态和模型信息作为MCP资源
## 用法 📚
如果您下载了此仓库，您可以通过添加以下配置来配置您的MCP客户端（例如VSCode）以使用服务器：
```json
"odoo": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
".",
"odoo-fast-mcp"
],
"envFile": "${workspaceFolder}/.env"
},
```
在其他项目中，您可以像这样使用它：
```json
"odoo": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/okolovmark/odoo-fast-mcp",
"odoo-fast-mcp"
],
"envFile": "${workspaceFolder}/.env"
},
```
## 可用工具 🛠️
### 连接工具
| 工具 | 描述 |
| --- | --- |
| `connect` | 连接并认证到Odoo服务器 |
| `disconnect` | 从当前会话断开连接 |
| `list_databases` | 列出Odoo服务器上的可用数据库 |
| `get_server_version` | 获取连接的Odoo服务器版本 |
| `get_connection_status` | 获取当前连接状态和用户信息 |
### 读取操作
| 工具 | 描述 |
| --- | --- |
| `search` | 搜索匹配域名过滤器的记录ID |
| `read` | 按ID读取特定记录 |
| `search_read` | 在单个操作中搜索和读取记录（推荐） |
| `search_count` | 统计匹配域名的记录 |
| `name_search` | 按名称搜索记录，模糊匹配 |
### 写入操作
| 工具 | 描述 |
| --- | --- |
| `create` | 在模型中创建新记录 |
| `write` | 更新现有记录 |
| `unlink` | 删除记录（破坏性） |
### 元数据工具
| 工具 | 描述 |
| --- | --- |
| `get_model_fields` | 获取模型的字段定义 |
| `list_models` | 列出Odoo实例中所有可用的模型 |
### 高级工具
| 工具 | 描述 |
| --- | --- |
| `execute` | 在Odoo模型上执行任意方法 |
| `get_report` | 生成并保存Odoo报告为PDF |
## 配置 ⚙️
使用您的Odoo连接详细信息创建`.env`文件：
```bash
# 复制示例文件
cp .env.example .env
# 使用您的设置编辑
ODOO_URL=http://localhost:8069
ODOO_DATABASE=your_database
ODOO_USERNAME=admin
ODOO_PASSWORD=admin
ODOO_TIMEOUT=30
```
服务器将在启动时使用这些凭证自动连接。
您也可以直接在`.env`文件之外设置环境变量。
## 域名语法 📝
Odoo域名是用于筛选记录的条件列表：
```python
# 基本语法
[["field", "operator", "value"]]
# 常见运算符
=, !=, >, >=, <, <=, like, ilike, in, not in
# 组合条件（隐含AND）
[["active", "=", true], ["name", "ilike", "john"]]
# 显式运算符
["&", ["field1", "=", "value1"], ["field2", "=", "value2"]] # AND
["|", ["field1", "=", "value1"], ["field2", "=", "value2"]] # OR
["!", ["field", "=", "value"]] # NOT
```
## MCP资源 📦
服务器还公开了这些MCP资源：
- `odoo://status` - 当前连接状态
- `odoo://models` - 所有可用模型的列表
- `odoo://model/{model_name}/fields` - 特定模型的字段定义
---
## 使用`uv`创建虚拟环境 🔧
### 快速步骤
1. 在项目根目录中创建虚拟环境（种子`pip`、`setuptools`、`wheel`）：
```bash
uv venv .venv --seed
# 或选择Python版本：
uv venv -p python3.11 .venv
```
2. 激活虚拟环境：
```bash
source .venv/bin/activate
```
3. 将项目依赖项安装到活动环境中：
```bash
uv sync --active
```
## 安装应用程序 📦
一旦虚拟环境设置并激活：
1. **安装应用程序及其依赖项：**
```bash
uv sync
```
这以可编辑模式安装`odoo-fast-mcp`包以及运行时依赖项（`OdooRPC`、`fastmcp`）。
2. **用于开发（包括代码检查和类型检查工具）：**
```bash
uv sync --extra dev
```
这将`ruff`（代码检查器/格式化器）和`ty`（类型检查器）添加到环境中。
## 运行服务器 🏃
### 标准输入传输（默认）
```bash
# 在当前目录中使用.env文件运行
odoo-fast-mcp
# 使用自定义.env文件路径运行
odoo-fast-mcp --env /path/to/.env
# 使用调试日志运行
odoo-fast-mcp --debug
# 或直接运行
python -m odoo_fast_mcp.server
```
### HTTP传输（可流式HTTP）
HTTP传输将MCP服务器变成一个可通过URL访问的Web服务。这对于MCP应用程序、远程部署和多客户端设置是必需的。
```bash
# 在默认端口8000上启动HTTP服务器
odoo-fast-mcp --transport http
# 自定义主机和端口
odoo-fast-mcp --transport http --host 127.0.0.1 --port 3001
# 使用调试日志
odoo-fast-mcp --transport http --port 3001 --debug
```
服务器将在`http://<host>:<port>/mcp`处可用。
您还可以通过`.env`文件中的环境变量配置传输：
```bash
MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8000
```
> **注意：** 命令行参数优先于环境变量，环境变量优先于默认值。
### SSE传输（旧版）
```bash
odoo-fast-mcp --transport sse --port 8000
```
### 从MCP客户端连接（HTTP模式）
当使用HTTP传输时，请配置您的MCP客户端通过URL连接而不是标准输入：
```json
"odoo": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
```
## 已知限制 ⚠️
### 报告下载（get_report）
由于Odoo 16+中的CSRF保护，`get_report`工具无法直接下载报告。调用时，它将：
1. 验证Odoo中存在报告
2. 返回报告元数据（名称、report_name、模型）
3. 引发带有指导的`NotImplementedError`
**解决方法：**
- 使用Odoo Web界面手动下载报告
- 在Odoo中设置计划操作以生成并存储报告为附件
- 对`ir.attachment`使用`search_read`工具检索存储的报告附件
---
如果您想要不同的工作流程（例如，使用系统站点包或自定义提示），请运行`uv help venv`以获取更多选项。
