Skip to content
Back to search

odoo-mcp

MCP server that gives AI agents safe, typed access to Odoo ERP: guarded reads, sales/stock/invoice tools, human-confirmed writes. MCP SDK 2.x.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/affifariza04--odoo-mcp/badge.svg)](/listings/affifariza04--odoo-mcp)

HTML

<a href="/listings/affifariza04--odoo-mcp"><img src="/api/listings/affifariza04--odoo-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 134 lines
  1. # odoo-mcp
  2. **An MCP server that lets AI agents (Claude, ChatGPT, Cursor, any MCP client) work with an Odoo ERP — safely.**
  3. Ask *"who should we chase for payment this week?"* or *"draft a quote for Hotel Arunika: 20 kg House Blend"* and the agent
  4. calls typed, guarded tools instead of getting raw database access.
  5. [![ci](https://github.com/affifariza04/odoo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/affifariza04/odoo-mcp/actions/workflows/ci.yml)
  6. ![python](https://img.shields.io/badge/python-3.12%20%7C%203.13-3776AB) ![mcp](https://img.shields.io/badge/MCP%20SDK-2.x%20(2026--07--28)-111) ![license](https://img.shields.io/badge/license-MIT-green)
  7. Built on the **MCP Python SDK 2.x** (protocol `2026-07-28`): structured tool output, tool annotations, and
  8. human-in-the-loop confirmation through the new `Resolve` / `Elicit` flow.
  9. ---
  10. ## Why
  11. Most "chat with your ERP" demos hand the model a database connection and hope. In a real company that is a non-starter:
  12. finance data, customer data and the ability to create documents all need guardrails. This server is opinionated about that:
  13. | Concern | What odoo-mcp does |
  14. |---|---|
  15. | **Least privilege** | Read-only by default. Writes need `ODOO_MCP_MODE=readwrite` *and* the model must be in an allow-list (only `sale.order`). |
  16. | **Human in the loop** | `create_quotation` shows the human a summary (customer, lines, total) and only writes on an explicit *Confirm*. Decline/cancel writes nothing. Quotes are created as **draft**, never confirmed or sent. |
  17. | **No data exfiltration** | Model allow-list; credential/token/binary fields (`password`, `api_key`, `totp_secret`, `image_1920`…) can't be read *or* filtered on. Row limits are clamped. |
  18. | **Well-formed requests only** | Odoo domains are validated (shape + operator allow-list) before they reach Odoo. |
  19. | **Errors the model can fix** | Anticipated failures (policy, bad dates, unknown ids) come back as tool errors with a clear message; unexpected exceptions are hidden from the model and logged. |
  20. | **API keys, not passwords** | Authenticates with an Odoo API key over the external API. |
  21. ## Tools
  22. | Tool | Kind | What it does |
  23. |---|---|---|
  24. | `find_customers(query)` | read | Customers by name, email or city |
  25. | `check_stock(query?, only_low?)` | read | On-hand qty per product, flagged `ok` / `low` / `out` — a reorder list |
  26. | `sales_report(date_from, date_to, group_by)` | read | Confirmed sales grouped by `month`, `customer` or `product` (via `read_group`) |
  27. | `overdue_invoices(as_of?)` | read | Unpaid posted invoices past due, most overdue first |
  28. | `search_records(model, domain, fields, limit, order)` | read | Guarded generic `search_read` for anything else |
  29. | `create_quotation(customer_id, lines)` | **write** | Draft quotation, after human confirmation |
  30. Plus a resource (`odoo://models`: what is exposed and whether writes are on) and a prompt
  31. (`month_end_review`: sales vs last month, who to chase, what to reorder).
  32. Every tool returns **typed, structured output** (Pydantic models → JSON Schema), so clients can render tables
  33. and agents don't have to parse prose.
  34. ## Try it in 30 seconds (no Odoo needed)
  35. Without `ODOO_URL` the server runs against a built-in demo company (a fictional coffee roaster with customers,
  36. products, orders and invoices):
  37. ```bash
  38. git clone https://github.com/affifariza04/odoo-mcp && cd odoo-mcp
  39. uv sync
  40. uv run python examples/demo.py # launches the server over stdio and runs an agent-style session
  41. ```
  42. ```text
  43. > overdue_invoices({"as_of": "2026-11-22"})
  44. INV/2026/0004 PT Sinar Retail due 2026-10-02 51 days 12,540,000
  45. INV/2026/0008 Lantai Dua Coffee due 2026-11-16 6 days 5,050,000
  46. [human is asked]
  47. Create a draft quotation for Hotel Arunika (total 7,940,000)?
  48. 20 x House Blend 1kg
  49. 12 x Gayo Arabica 250g
  50. [human clicks: Confirm]
  51. > create_quotation(...) -> {"name": "S00013", "customer": "Hotel Arunika", "total": 7940000.0, "state": "draft"}
  52. ```
  53. ## Use it with Claude Desktop / Cursor
  54. ```jsonc
  55. {
  56. "mcpServers": {
  57. "odoo": {
  58. "command": "uvx",
  59. "args": ["--from", "git+https://github.com/affifariza04/odoo-mcp", "odoo-mcp"],
  60. "env": {
  61. "ODOO_URL": "https://your-company.odoo.com",
  62. "ODOO_DB": "your-db",
  63. "ODOO_USER": "you@company.com",
  64. "ODOO_API_KEY": "…", // Odoo → Preferences → Account Security → New API Key
  65. "ODOO_MCP_MODE": "readonly" // or "readwrite" to enable create_quotation
  66. }
  67. }
  68. }
  69. }
  70. ```
  71. Remote/HTTP clients: `odoo-mcp --http` serves Streamable HTTP.
  72. ## Architecture
  73. ```mermaid
  74. flowchart LR
  75. A[AI agent / MCP client] -- tools/call --> S[MCPServer<br/>typed tools]
  76. S --> P[Policy<br/>allow-lists · field filter · domain validation · limits]
  77. P --> B{Backend}
  78. B -- XML-RPC + API key --> O[(Odoo 14–18)]
  79. B -- in-memory --> D[(Demo company)]
  80. S -. Elicit: confirm? .-> H[Human]
  81. ```
  82. ```
  83. src/odoo_mcp/
  84. server.py tools, resource, prompt, confirmation resolver, entry point
  85. policy.py guardrails (pure, unit-tested)
  86. backend.py XmlRpcBackend (real Odoo) + DemoBackend (in-memory, with an Odoo domain evaluator)
  87. tests/ policy + domain unit tests, end-to-end tests through a real MCP client
  88. examples/ stdio demo session
  89. ```
  90. ## Tests
  91. ```bash
  92. uv run pytest -q # 20 tests
  93. uv run ruff check .
  94. ```
  95. The end-to-end tests connect a real `mcp.Client` to the server and cover: tool listing and annotations,
  96. each business tool's numbers on the demo company, policy errors surfacing to the model, read-only mode
  97. refusing writes, and the confirmation flow (accept → created; reject/decline → nothing written).
  98. CI runs the suite on Python 3.12 and 3.13, plus the stdio demo.
  99. ## Roadmap
  100. - Purchase suggestions from stock velocity (`suggest_reorder`)
  101. - Per-user auth on the HTTP transport (OAuth), mapping each user to their own Odoo API key
  102. - Audit log of every write the agent proposes and what the human decided
  103. ---
  104. Built by [Affif Ariza Adiwijaya](https://affifariza04.github.io/portfolio/): 1.5 years building on Odoo, now building AI tooling around it. MIT licensed.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.