ams-odoo-mcp-connector
Provides read access to Odoo business data (search/read records, list installed modules) and enables creating records with a human-approval gate, respecting strict allowlists.
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., "@ams-odoo-mcp-connector Find 3 sales orders with their customer names."
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.
AMS Odoo MCP Connector
Python MCP (Model Context Protocol) server that gives an AI assistant (such as Claude) access to an Odoo instance: read business data and -only with human approval- create records. It is a standalone intermediary service (not a module inside Odoo) and instance-agnostic: it works against any Odoo 18/19 by changing only configuration.
Each person runs their own copy with their own Odoo credentials. No credentials travel in this repository.
For business context and design principles, see CLAUDE.md.
1. Requirements
Python 3.11+ (tested on 3.13)
git
An Odoo 18/19 instance reachable from your machine and an API user (starting with read-only permissions is ideal).
Optional: Docker (for the containerized connection checks).
Related MCP server: Odoo MCP Server
2. Quickstart
git clone <REPO-URL> ams-odoo-mcp-connector
cd ams-odoo-mcp-connectorCreate the virtual environment and install the package:
Windows (PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"3. Configure your credentials
Copy the template and edit it with your Odoo details:
cp .env.example .envVariable | Required | Description |
| yes | Base URL of your Odoo instance. |
| yes | Database name. |
| yes | API user. |
| yes | Password / API key. |
| for writes | Secret that signs the approval gate. Without it, record creation is disabled. |
| no | Pins the major version (e.g. |
| no | Directory for the allowlists (defaults to |
| no | Log level (to stderr). |
Generate your own ODOO_MCP_APPROVAL_SECRET (required to create records):
python -c "import secrets; print(secrets.token_urlsafe(48))"The
.envis git-ignored: it is yours and local. Never commit it.
4. Verify that everything loads
ams-odoo-mcp-config # prints your config with secrets maskedIf you have connectivity to Odoo, run the read-only connection check:
python smoke_test.py # login + version + a harmless search_read. Writes NOTHING.Expected success output: OK Handshake correct.
5. Connect it to Claude
The assistant launches the server as a local process (stdio). It carries no credentials:
the server reads your .env on its own.
Claude Desktop
Edit the configuration file:
Windows:
%APPDATA%\Claude\claude_desktop_config.json(in the Microsoft Store version, the real path is under...\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json)macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Add (or merge) this block, with your paths:
{
"mcpServers": {
"ams-odoo": {
"command": "RUTA-A-TU/.venv/Scripts/python.exe",
"args": ["-m", "odoo_mcp.server"],
"cwd": "RUTA-ABSOLUTA-A-ESTE-REPO"
}
}
}(on macOS/Linux the command is RUTA-A-TU/.venv/bin/python.)
Quit Claude Desktop completely (tray icon -> Quit) and reopen it.
Claude Code
cp .mcp.json.example .mcp.jsonEdit .mcp.json with the path to your venv Python and to this repo. When you open the
project, Claude Code will ask you to approve the server.
6. Try it
In a Claude chat, ask for example:
"List the modules installed in Odoo." -> uses
odoo_list_modules."Find 3 sales orders with their customer." -> uses
odoo_search_read."Schedule an installation." ->
odoo_create_recordwill return a proposal for you to approve; nothing is created until you confirm.
The three tools
Tool | What it does | Type |
| Reads records from an allowed model, with bounded pagination. | Read |
| Lists the modules installed in the instance. | Read |
| Creates a record after human approval (two-phase gate). | Write |
Write gate: the first call (without approval_token) returns a
PROPOSAL with a signed token and creates nothing; the second, with that token
approved by a human, is the only one that executes the create. The token is signed
(it cannot be forged), bound to the exact values, and expires in 5 minutes.
Governance and security
Strict allowlists in
config/: only the listed models can be read/created. The write list starts scoped tocalendar.event.Human-in-the-loop for all writes (gate + signed token).
Secrets only in configuration (never in code, logs, or Docker image).
Never assume: if it cannot confirm something in Odoo, it says so; a permissions problem is never reported as "the data does not exist".
Architecture (odoo_mcp package, in src/)
Module | Responsibility |
| Typed config from environment/ |
| Stateless JSON-RPC transport, authentication, re-login, safe connection backoff. |
| High-level |
| Instance version and installed modules; availability of a model. |
| Allowlists, field validation, pagination cap, availability cache. |
| Error hierarchy + |
| HMAC token for the write gate (propose->commit). |
| Logic of the 3 tools (independent of the MCP runtime). |
| MCP wiring (stdio), lifespan, tool registration. |
Development
pytest # 68 tests (use mocks; no Odoo required)
ruff check src tests # lintContainerized connection checks (Docker, hardened)
Credentials are injected from your .env; they do not live in the image. The container
runs non-root, read-only rootfs, no capabilities, no privilege escalation.
docker compose build smoke
docker compose run --rm smoke # read-only: login + version + search_read
docker compose run --rm smoke python write_test.py # controlled write: create -> verify -> deleteTroubleshooting
Symptom | Likely cause / fix |
| The |
| Incorrect |
| Network/VPN/firewall/URL: the instance is not reachable from your machine. |
Claude Desktop shows "failed" | Check the |
Creation says "disabled" |
|
(c) 2026 onePhase - Proprietary. See LICENSE.
Available Tools
3 toolsodoo_create_recordA
Create a record in an Odoo model allowed for writing, ONLY after human approval. Call WITHOUT 'approval_token': returns a PROPOSAL (preview + token) and creates nothing. To execute, a human resends the same call with the same 'model'/'values' and the received 'approval_token'.
Inputs: model (required), values (required), approval_token. Returns: object
odoo_list_modulesARead-only
List the modules installed on the Odoo instance (name, description, version).
Inputs: no named parameters. Returns: object
odoo_search_readARead-only
Read records from an allowed Odoo model. 'domain' is an Odoo search domain (list of conditions); 'fields' limits the columns; 'limit'/'offset' paginate (the limit is bounded to the configured maximum).
Inputs: model (required), limit, domain, fields, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct operation: reading records, listing modules, and creating records with an approval flow. There is no overlap in purpose or ambiguous boundaries between them.
All tool names follow the consistent pattern 'odoo_' + verb_noun (search_read, list_modules, create_record). The naming is uniform and predictable, despite mixing verbs like 'search' and 'list'.
With only 3 tools, the server is on the lean side but still within a reasonable range for a focused connector. Each tool provides a distinct function, though the count is minimal.
The tool surface lacks essential CRUD operations such as update and delete, which are common in Odoo data access. While read and create are covered, missing write operations and additional search capabilities create significant gaps for a general-purpose connector.
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Odoo MCP connector for ChatGPT and Claude: ask sales, invoices and stock in plain words. Read-only.
Odoo virtual employee via MCP: query, create, modify records, workflows, PDFs, and activities.
The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceAn MCP server that enables AI assistants like Claude to interact with Odoo ERP systems through natural language, allowing users to search, create, update, and manage business data in their Odoo instance.16,479 PyPI416Mozilla Public 2.0
- AlicenseBqualityDmaintenanceAn MCP server that enables AI assistants to interact with Odoo ERP apps like Inventory, CRM, Sales, and Manufacturing. It allows users to read, create, and manage Odoo records and workflows using natural language commands.2511 npm1ISC
- AlicenseNot gradedqualityDmaintenanceAn MCP server that connects AI assistants to Odoo ERP instances via the built-in XML-RPC API without requiring any additional addons. It enables users to search, create, update, and manage Odoo records and models through natural language.MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to interact with Odoo ERP, allowing natural language queries, record creation, updates, and deletions.LGPL 3.0