{
  "markdown": "# odoo-pulse\n\n[![CI](https://github.com/minhhq-a1/odoo-pulse/actions/workflows/ci.yml/badge.svg)](https://github.com/minhhq-a1/odoo-pulse/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/odoo-pulse)](https://pypi.org/project/odoo-pulse/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n<!-- mcp-name: io.github.minhhq-a1/odoo-pulse -->\n\n**An AI business analyst for your [Odoo](https://www.odoo.com) ERP.** Ask one\nquestion, get one answer — numbers, highlights, risks, and a verdict\n(on-track / at-risk / off-track) — over the [Model Context\nProtocol](https://modelcontextprotocol.io). CRUD bridges to Odoo already exist;\nthis is the analytics layer that sits on top.\n\n![business_pulse — a one-call company briefing](assets/business_pulse.gif)\n\n## The analyst tools\n\nEach tool answers a whole management question in a single call, returning a\nstructured report with a verdict — not a raw dump you have to interpret.\n\n| Tool | Answers |\n| --- | --- |\n| `business_pulse` ⭐ | The morning briefing: yesterday's sales, new leads, overdue invoices, late tasks, who's off — with a company-wide verdict |\n| `pipeline_review` | CRM funnel by stage, stalled deals, weighted revenue, recent win rate |\n| `sales_snapshot` | Revenue this period vs last (Δ%), top customers/products, stale quotations |\n| `receivables_health` | AR/AP aging buckets, % overdue, top debtors |\n| `inventory_risk` | Shortages (negative forecast) and dead stock |\n| `absence_overview` | Who's off this week, pending approvals, thin-coverage departments |\n| `procurement_watch` | Purchasing: late receipts, stale RFQs, open spend per vendor |\n| `production_health` | Manufacturing: orders behind their planned start, stuck WIP |\n| `project_profitability` | Projects: hours logged vs allocated, cost/revenue/margin, budget burn verdict |\n| `project_budget` | Budget vs actual per project, line by line — over-plan lines and spend the budget doesn't capture |\n| `team_workload` · `project_status_report` · `standup_digest` | Project delivery: overloaded members, at-risk projects, and a daily stand-up digest |\n\nEvery money-reporting tool takes an optional\n`company=` filter and flags\nmixed-currency totals instead of silently summing them; verdict cut-offs\n(stalled %, overdue %, growth %) are parameters, so you can calibrate them\nto your business.\n\n### Timezone semantics\n\nAll report tools take `timezone_offset` (default `7`). Odoo stores datetime\nfields in UTC; the tools shift them by `timezone_offset` hours before\nbucketing by calendar day, and day windows in domains are expressed as UTC\ndatetime boundaries. Date-only fields (e.g. `project.milestone.deadline`,\n`invoice_date_due`, `project.task.date_deadline`) are compared as-is.\n\n### Version-dependent fields\n\n`find_partner` searches `mobile` only on instances that still have it (removed in Odoo 19), and `list_timesheets` reports an actionable error when `hr_timesheet` is not installed.\n\nUnder the hood it's the standard Odoo XML-RPC external API — nothing to install\ninside Odoo, works on Odoo Online, Odoo.sh, and on-premise. **Requires\nOdoo 18+**: the generic tools (`search_read`, `read_records`, …) still run on\nolder versions, but the report tools are not guaranteed there.\n\n## Try the playground\n\nNo Odoo account? Boot a demo Odoo pre-seeded with a story to tell (a stalled\ndeal, a 90-day-overdue invoice, a stock shortage, someone off today):\n\n```bash\ndocker compose -f deploy/playground/compose.yml up -d\n```\n\nFirst boot pulls ~4 GB of images (Odoo + Postgres) and seeds the demo data —\nallow 5-10 minutes depending on your connection. Then point Claude at it and\nask it to **`run business_pulse`**. Full walkthrough:\n[docs/guides/playground.md](docs/guides/playground.md).\n\n## Install & connect\n\nAdd it to Claude Code (no install step — `uvx` fetches it):\n\n```bash\nclaude mcp add odoo-pulse \\\n  --env ODOO_URL=https://acme.odoo.com \\\n  --env ODOO_DB=acme \\\n  --env ODOO_USERNAME=you@example.com \\\n  --env ODOO_API_KEY=your-api-key \\\n  --env ODOO_READ_ONLY=true \\\n  -- uvx odoo-pulse\n```\n\nGenerate the API key in Odoo under **Settings → Users → (your user) → Account\nSecurity → New API Key**. Config for **Claude Desktop** and **Cursor**, plus pip\nand Docker alternatives: [docs/guides/install.md](docs/guides/install.md). If a key may have\nbeen exposed, see [If an API key may have been\nexposed](docs/guides/install.md#if-an-api-key-may-have-been-exposed).\n\nOr one-click:\n\n[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=odoo-pulse&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyJvZG9vLXB1bHNlIl0sICJlbnYiOiB7Ik9ET09fVVJMIjogImh0dHBzOi8vYWNtZS5vZG9vLmNvbSIsICJPRE9PX0RCIjogImFjbWUiLCAiT0RPT19VU0VSTkFNRSI6ICJ5b3VAZXhhbXBsZS5jb20iLCAiT0RPT19BUElfS0VZIjogInlvdXItYXBpLWtleSIsICJPRE9PX1JFQURfT05MWSI6ICJ0cnVlIn19)\n[![Install in VS Code](https://img.shields.io/badge/VS%20Code-Install%20odoo--pulse-0098FF?logo=githubcopilot&logoColor=white)](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)\n\n## Read-only by default, safe writes when you want them\n\nThe server is read-only out of the box (`ODOO_READ_ONLY=true`). Writes require\nfour independent controls to line up: `ODOO_READ_ONLY=false`,\n`ODOO_WRITABLE_MODELS` (a comma-separated model allow-list),\n`ODOO_ALLOW_DELETE=true` additionally for deletes, and a per-call `confirm=true`\n— every write tool returns a dry-run preview without it. System models are never\nwritable. Details: [docs/reference/tools.md#write-operations](docs/reference/tools.md#write-operations).\n\n## More tools\n\nBeyond the analyst reports, there are ~60 model-aware query tools spanning CRM,\nSales, Inventory, Accounting, HR, Project, Manufacturing, PoS, and Enterprise\napps — opt in via `ODOO_TOOL_GROUPS`. Full catalogue and configuration:\n[docs/reference/tools.md](docs/reference/tools.md).\n\n## Testing\n\nThe suite mocks the XML-RPC layer, so **no real Odoo or network is needed**:\n\n```bash\npip install -e \".[dev]\"\npytest\n```\n\nFor a live check against a real Odoo (read-only), see\n[docs/reference/tools.md#live-smoke-test-against-a-real-odoo](docs/reference/tools.md#live-smoke-test-against-a-real-odoo).\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 6591,
  "sha": "b0abdbb845b53b5700a655390d66b487753030a22783795f1f8111830b38c911",
  "repo_slug": "minhhq-a1/odoo-pulse",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_minhhq_a1_odoo_pulse_4e36443e/readme"
}