Odoo MCP Server
Provides tools for reading and safely writing Odoo 18 business data, including CRM leads, customers, sales orders, invoices, and sales pipeline summaries, with support for lead creation, preview-before-confirm, and read-only mode.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Odoo MCP Server Can you summarize our sales pipeline and list unpaid invoices?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Odoo MCP Server
An MCP server that lets an LLM (Claude Desktop, or any MCP host) read and carefully write Odoo 18 data: CRM leads, customers, sales orders and invoices.
This is a learning/portfolio project. It runs against a local Odoo with demo data only, the code is kept small, and comments explain the MCP concepts where they first appear.

27-second animated walkthrough made with Remotion from real tool output on the demo database. Also available as MP4; source in demo-video/.
Tool | What it does | Writes? |
| CRM leads and opportunities, biggest expected revenue first | no |
| Customers/contacts by name, email or phone | no |
| Quotations and sales orders ( | no |
| Posted customer invoices not fully paid, with days overdue | no |
| Opportunity count, expected and weighted revenue per stage | no |
| Preview, then create a CRM lead | yes, disabled by |
Every tool returns compact JSON. Relations are resolved to names, Odoo's False becomes null, and results are capped at 50 records.
Architecture
flowchart LR
L["LLM<br/>(Claude)"] <--> H["MCP host<br/>Claude Desktop / MCP Inspector"]
H <-->|"JSON-RPC over stdio<br/>tools/list · tools/call"| T
subgraph S["odoo-mcp · Python, this repo"]
T["server.py<br/>MCPServer + tools"] --> F["formatting.py<br/>shape compact JSON"]
T --> C["odoo_client.py<br/>OdooClient"]
C --- E["config.py<br/>.env settings"]
end
C <-->|"XML-RPC<br/>/xmlrpc/2/common · /xmlrpc/2/object"| O["Odoo 18 Community<br/>Docker :8069"]
O <--> P[("Postgres 16<br/>Docker volume")]How one question flows through the system:
The host starts
odoo-mcpas a subprocess and asks fortools/list. It gets each tool's name, description (the docstring) and input JSON schema (from the type hints).You ask "who owes us money?". The LLM picks
get_unpaid_invoicesand the host sendstools/call.server.pycallsOdooClient, which logs in once over XML-RPC and runssearch_readonaccount.move.formatting.pytrims each record to a few fields. The host passes the JSON back to the LLM, which writes the answer.
src/odoo_mcp/
server.py MCP server and tools (start here)
odoo_client.py XML-RPC wrapper with clear error types
formatting.py pure functions: raw Odoo record -> compact dict
config.py loads .env (by absolute path)
scripts/ init_db.sh, check_odoo.py, show_leads.py
tests/ unit tests (mocked) + optional integration testsRelated MCP server: Odoo MCP Server
Setup
Prerequisites: Docker Desktop, uv, and Node.js 22+ (only for the MCP Inspector).
# 1. Start Odoo 18 + Postgres 16
docker compose up -d
# 2. Create the "odoo_demo" database with demo data + CRM, Sales, Invoicing (~1 min)
./scripts/init_db.sh
# 3. Check it (login admin/admin, modules installed, demo records present)
python3 scripts/check_odoo.py
# 4. Python environment + settings
cp .env.example .env # defaults match the local Docker setup
uv sync
# 5. Prove the API connection
uv run python scripts/show_leads.pyOdoo itself is at http://localhost:8069 (log in as admin / admin).
Variable | Default | Meaning |
|
| Odoo base URL |
|
| Database name |
|
| Login |
|
| Password or (better) an Odoo API key |
|
|
|
Try it with the MCP Inspector
The Inspector is a small UI that acts as an MCP host, so you can call the tools by hand.
npx @modelcontextprotocol/inspector uv --directory /path/to/odoo-mcp-server run odoo-mcpOpen the printed http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=… URL and switch the uv server on. Then go to Tools, pick a tool, and click Execute Tool.
The same thing from the terminal (handy for scripts):
DIR=/path/to/odoo-mcp-server
npx @modelcontextprotocol/inspector --cli --method tools/list uv --directory $DIR run odoo-mcp
npx @modelcontextprotocol/inspector --cli --method tools/call --tool-name pipeline_summary uv --directory $DIR run odoo-mcp
npx @modelcontextprotocol/inspector --cli --method tools/call --tool-name list_leads \
--tool-arg stage=Proposition --tool-arg limit=3 uv --directory $DIR run odoo-mcp
# read-only mode: create_lead disappears from the list
npx @modelcontextprotocol/inspector --cli -e ODOO_READ_ONLY=true --method tools/list uv --directory $DIR run odoo-mcpInspector 2.16 asks for Node ^22.23.4 || ^24.22.1 || >=26.12.1. On an older patch release, npm prints an EBADENGINE warning, but the Inspector still works.
Connect to Claude Desktop
Open Claude Desktop → Settings → Developer → Edit Config. That opens
~/Library/Application Support/Claude/claude_desktop_config.json.Add the server. Use absolute paths: GUI apps don't see your shell's
PATH, so"command": "uv"alone usually fails. Find yours withwhich uvandpwd.{ "mcpServers": { "odoo": { "command": "/absolute/path/to/uv", "args": [ "--directory", "/absolute/path/to/odoo-mcp-server", "run", "odoo-mcp" ] } } }Credentials come from the project's
.env. You can override any variable per host with an"env"block, for example"env": { "ODOO_READ_ONLY": "true" }for a safe, read-only connection.Quit Claude Desktop completely (⌘Q) and reopen it. "odoo" should appear under the tools/connectors menu.
If it doesn't show up, check the logs in
~/Library/Logs/Claude/(look for themcp*files).
Example prompts
"Summarize my sales pipeline by stage. How much revenue is weighted by probability?"
"Show the three biggest opportunities in the Proposition stage and who owns them."
"Which customers have unpaid invoices, and how many days overdue are they?"
"Find the contact details for Wood Corner."
"List the five most recent confirmed sales orders."
"Create a lead 'Standing desks for Ready Mat', expected revenue 8,000, email buyer@readymat.example." Claude shows a preview first; reply "yes, create it" to confirm.
How writes are kept safe
Preview, then confirm.
create_leadwrites nothing unlessconfirm=true. The first call returns exactly what would be created, so the user can approve it. This step relies on the LLM following instructions, so it's a convenience, not a guarantee.Tool annotations. Read tools carry
read_only_hint=true.create_leadcarriesread_only_hint=false, so hosts like Claude Desktop ask you before running it.ODOO_READ_ONLY=trueis the hard switch. Write tools are not registered at all, so the LLM never sees them. As a second line of defence,OdooClient.create()refuses to run.Bounded inputs and outputs. Inputs are checked against the schema (
limit1–50, an enum for order state) before any Odoo call, and outputs are trimmed to a few fields per record.Readable errors. Odoo failures become
ToolError, the only error type whose message the LLM can read. For example: "Cannot reach Odoo… Is Odoo running?" or "Login failed…". Text from any other exception is hidden from the model by the SDK.
Tests
uv run pytest # everything (integration tests skip if Odoo is down)
uv run pytest -m "not integration" # unit tests only, no Odoo needed
uv run pytest -m integration -v # only the live tests against local Odootests/test_odoo_client.pymocksxmlrpc.client.ServerProxy. It covers login caching, bad credentials, unknown databases, network errors, trimming of Odoo tracebacks,execute_kwarguments and the read-only guard.tests/test_formatting.pychecks how raw records are trimmed into compact JSON.tests/test_tools.pyinjects a fake client. It calls the tools directly, and also goes through the real MCP protocol using the SDK's in-memoryClient. That covers schemas,is_errorresults, hidden exception text and read-only tool registration.tests/test_integration.pymakes read-only calls against the running demo database.
MCP concepts in this repo
Concept | Where |
Server object, |
|
Tool = function + docstring + type hints |
|
Per-parameter schema (descriptions, limits, enums) |
|
Tool annotations |
|
Errors the model can read |
|
stdio transport (never |
|
Conditional tools |
|
The code targets the MCP Python SDK v2 (mcp>=2.3). In v2, FastMCP was renamed to MCPServer (from mcp.server import MCPServer), and ToolError lives in mcp.server.mcpserver.exceptions. Many tutorials still show the v1 from mcp.server.fastmcp import FastMCP import, which no longer exists.
Next steps
React Native mobile client. A phone can't spawn a stdio subprocess. Run the server over the Streamable HTTP transport (
mcp.run(transport="streamable-http")) behind HTTPS. Then build an RN app that sends the user's message plus the tool list to an LLM API and forwards tool calls to this server. Authentication becomes mandatory at that point (see below).More Odoo models. Products and stock levels, CRM activities and follow-ups, purchase orders, HR. Add MCP resources (e.g.
odoo://lead/{id}) and prompts (e.g. a "weekly sales review" template), plus a few more safe write tools (log a note, schedule an activity) using the same preview/confirm pattern.Auth hardening.
Use an Odoo API key instead of the admin password.
Connect as a dedicated low-privilege Odoo user (e.g. Sales: own documents only), so Odoo's access rules limit what the LLM can see.
Keep secrets in the macOS Keychain or a secrets manager instead of
.env.For HTTP deployments, add OAuth (the SDK supports
auth=/token_verifier=), rate limiting and audit logging of every write.Stop passing raw Odoo error text (which can include internal hostnames) back to the model.
Odoo 19+ API. Odoo 19 introduced the JSON-2 API (
POST /json/2/<model>/<method>with an API key as a bearer token). XML-RPC/JSON-RPC are deprecated and scheduled for removal in Odoo 22. Because every call goes throughOdooClient.execute_kw, switching is a change to one class.
License
Available Tools
6 toolscreate_leadA
Create a new CRM lead in Odoo, in two steps.
1. Call with confirm=false (the default): nothing is written; you get a preview
of exactly what would be created. Show it to the user.
2. If the user approves, call again with the same arguments and confirm=true.
Inputs: name (required), email, confirm, partner_name, +1 more. Returns: object
get_sales_ordersARead-only
List sales orders and quotations, newest first, with customer, total and invoice status.
Inputs: limit, state. Returns: object
get_unpaid_invoicesARead-only
List posted customer invoices that are not (fully) paid, oldest due date first.
Includes amount still due and days overdue. Use for "who owes us money?" or "which invoices are overdue?".
Inputs: limit. Returns: object
list_leadsARead-only
List CRM leads and opportunities, highest expected revenue first.
Use for questions like "what's in the pipeline?", "show deals in Proposition"
or "who are our biggest prospects?". Each record has type "lead" (not yet
qualified) or "opportunity" (in the sales pipeline). `total` is the number of
matching records; `leads` holds at most `limit` of them.
Inputs: limit, stage. Returns: object
pipeline_summaryARead-only
Summarize the sales pipeline: number of opportunities and expected revenue per stage.
weighted_revenue = expected revenue x win probability. Covers active
opportunities only (not unqualified leads, not lost/archived deals).
Inputs: no named parameters. Returns: object
search_partnersARead-only
Find customers and contacts (Odoo partners) by name, email or phone.
Partners are companies or individual people; individuals may belong to a company.
Inputs: query (required), limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct resource or view: leads, partners, sales orders, unpaid invoices, pipeline aggregate, and lead creation. The only mild overlap is list_leads versus pipeline_summary, but one returns records and the other aggregates by stage, so the descriptions make the boundary clear.
Five of six names follow a clean verb_noun pattern (list_leads, search_partners, get_sales_orders, get_unpaid_invoices, create_lead). pipeline_summary is a noun-only outlier, but it is still readable and unambiguous.
Six tools is well-scoped for a CRM/sales assistant, with each tool covering a distinct question type (pipeline, contacts, orders, receivables, creation). No redundant or filler tools.
The surface is read-heavy with a single write path (create_lead): there is no update/advance lead, no close/won-lost action, no quotation or sales-order creation, and no invoice detail or payment marking. Core read workflows are covered, but lifecycle coverage is notably partial for a sales CRM.
Maintenance
Related MCP Connectors
Connect your Odoo to Claude and ChatGPT: ask about sales, stock, customers and invoices.
Odoo MCP connector for ChatGPT and Claude: ask sales, invoices and stock in plain words. Read-only.
Read, write and run Odoo actions from any AI app, as each user, with approval rules per colleague.
Connect AI to Odoo ERP 14-20: search, create, update and manage records in natural language.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to control any Odoo database via XML-RPC, with features for reading, writing, importing/exporting data, and generating intervention reports.32MIT
- AlicenseBqualityCmaintenanceConnects MCP clients like Claude to your Odoo ERP, enabling natural language queries, reports, and optional data modifications.9MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to securely access and perform CRUD operations on Odoo data through natural language, with granular permissions and dual REST/XML-RPC support.-
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to securely access and interact with Odoo data through natural language, supporting CRUD operations, attachments, and role-based permissions.-