内容
# odoo-pulse
[](https://github.com/minhhq-a1/odoo-pulse/actions/workflows/ci.yml)
[](https://pypi.org/project/odoo-pulse/)
[](LICENSE)
<!-- mcp-name: io.github.minhhq-a1/odoo-pulse -->
**一款适用于您的 [Odoo](https://www.odoo.com) 企业资源规划的 AI 商业分析工具。** 只需提出一个问题，即可获得一个答案——数字、亮点、风险和裁决（按时 / 风险 / 脱轨）——基于 [模型上下文协议](https://modelcontextprotocol.io)。 Odoo 的 CRUD 桥梁已经存在；这是在其上构建的分析层。
## 分析工具
每个工具都能回答一个完整的管理问题，只需一次调用，即可返回带有裁决的结构化报告——而不是您需要解读的原始数据。
| 工具 | 回答 |
| --- | --- |
| `business_pulse` ⭐ | 早晨简报：昨天的销售额、新线索、逾期发票、延迟任务、谁不在 — 附带公司范围的裁决 |
| `pipeline_review` | CRM 渠道按阶段划分、停滞交易、加权收入、近期成交率 |
| `sales_snapshot` | 当前期间与上一期间的收入（Δ%）、主要客户/产品、过期报价 |
| `receivables_health` | 应收/应付账款账龄桶、逾期百分比、主要债务人 |
| `inventory_risk` | 短缺（负预测）和滞销库存 |
| `absence_overview` | 本周谁不在、待批请假、部门覆盖不足 |
| `procurement_watch` | 采购：延迟收货、过期询价、供应商开放支出 |
| `production_health` | 制造：订单延迟启动、卡住的生产工序 |
| `project_profitability` | 项目：已记录小时数与分配小时数、成本/收入/利润率、预算支出裁决 |
| `team_workload` · `project_status_report` · `standup_digest` | 项目交付：成员超负荷、风险项目和每日站会摘要 |
每个与财务报告相关的工具都可选 `company=` 过滤器，并标记混合货币总额而不是静默求和；裁决截止值（停滞百分比、逾期百分比、增长率百分比）是参数，因此您可以根据您的业务进行调整。
### 时区语义
所有报告工具都采用 `timezone_offset`（默认为 `7`）。 Odoo 将 datetime 字段存储在 UTC；工具将它们偏移 `timezone_offset` 小时，然后按日历日分组，并且域中的日窗口以 UTC datetime 边界表示。仅日期字段（例如 `project.milestone.deadline`、`invoice_date_due`、`project.task.date_deadline`）直接比较。
### 版本依赖字段
`find_partner` 仅在仍具有它的实例上搜索 `mobile`（在 Odoo 19 中删除），并且 `list_timesheets` 在未安装 `hr_timesheet` 时报告一个可操作的错误。
在内部，它是标准的 Odoo XML-RPC 外部 API —— 无需在 Odoo 中安装，在 Odoo Online、Odoo.sh 和本地部署上都适用。 **需要 Odoo 18+**：通用工具（`search_read`、`read_records` 等）仍在较旧版本上运行，但报告工具不保证在这些版本上可用。
## 尝试游乐场
没有 Odoo 账户？启动一个预先植入了故事的演示 Odoo（一个停滞的交易，一个 90 天逾期的发票，一个库存短缺，今天有人不在）：
```bash
docker compose -f docker-compose.playground.yml up -d
```
首次启动会拉取约 4 GB 的镜像（Odoo + Postgres）并植入演示数据 — 根据您的连接速度，这可能需要 5-10 分钟。然后指向 Claude 并要求它 **`run business_pulse`**。完整的演练步骤：[docs/playground.md](docs/playground.md)。
## 安装和连接
将其添加到 Claude Code（无需安装步骤 — `uvx` 会获取它）：
```bash
claude mcp add odoo-pulse \
--env ODOO_URL=https://acme.odoo.com \
--env ODOO_DB=acme \
--env ODOO_USERNAME=you@example.com \
--env ODOO_API_KEY=your-api-key \
--env ODOO_READ_ONLY=true \
-- uvx odoo-pulse
```
在 Odoo 的 **设置 → 用户 →（您的用户）→ 账户安全 → 新的 API 密钥**下生成 API 密钥。适用于 **Claude Desktop** 和 **Cursor** 的配置，以及 pip 和 Docker 替代方案：[docs/install.md](docs/install.md)。
或一键安装：
[](https://cursor.com/en/install-mcp?name=odoo-pulse&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyJvZG9vLXB1bHNlIl0sICJlbnYiOiB7Ik9ET09fVVJMIjogImh0dHBzOi8vYWNtZS5vZG9vLmNvbSIsICJPRE9OX0RCIjogImFjbWUiLCAiT0RPT19VU0VSTkFNRSI6ICJ5b3VAZXhhbXBsZS5jb20iLCAiT0RPT19BUElfS0VZIjogInlvdXItYXBpLWtleSIsICJPRE9OX1JFQURfT05MWSI6ICJ0cnVlIn19)
[](https://vscode.dev/redirect/mcp/install?name=odoo-pulse&config=%7B%22name%22%3A%20%22odoo-pulse%22%2C%20%22command%22%3A%20%22uvx%22%2C%20%22args%22%3A%20%5B%22odoo-pulse%22%5D%2C%20%22env%22%3A%20%7B%22ODOO_URL%22%3A%20%22https%3A%2F%2Facme.odoo.com%22%2C%20%22ODOO_DB%22%3A%20%22acme%22%2C%20%22ODOO_USERNAME%22%3A%20%22you%40example.com%22%2C%20%22ODOO_API_KEY%22%3A%20%22your-api-key%22%2C%20%22ODOO_READ_ONLY%22%3A%20%22true%22%7D%7D)
## 默认只读，安全写入
服务器默认是只读的（`ODOO_READ_ONLY=true`）。写入需要四个独立的控制项同时满足：`ODOO_READ_ONLY=false`、`ODOO_WRITABLE_MODELS`（一个逗号分隔的模型允许列表）、`ODOO_ALLOW_DELETE=true` 另外还需要一个 `confirm=true` 的调用 — 每个写入工具都会返回一个 dry-run 预览。系统模型永远不可写入。详细信息：[docs/tools.md#write-operations](docs/tools.md#write-operations)。
## 更多工具
除了分析报告外，还有大约 60 个模型感知查询工具，涵盖 CRM、销售、库存、会计、人力资源、项目、制造、零售和企业应用程序 — 通过 `ODOO_TOOL_GROUPS` 进行选择。完整的目录和配置：[docs/tools.md](docs/tools.md)。
## 测试
该套件模拟了 XML-RPC 层，因此 **不需要真正的 Odoo 或网络**：
```bash
pip install -e ".[dev]"
pytest
```
有关针对真实 Odoo 进行实时检查（只读），请参见 [docs/tools.md#live-smoke-test-against-a-real-odoo](docs/tools.md#live-smoke-test-against-a-real-odoo)。
## 许可证
[MIT](LICENSE)
