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-connector

Create 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 .env

Generate your own ODOO_MCP_APPROVAL_SECRET (required to create records):

python -c "import secrets; print(secrets.token_urlsafe(48))"

The .env is git-ignored: it is yours and local. Never commit it.

4. Verify that everything loads

ams-odoo-mcp-config        # prints your config with secrets masked

If 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.json

Edit .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_record will return a proposal for you to approve; nothing is created until you confirm.

The three tools

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 to calendar.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/)

Development

pytest                    # 68 tests (use mocks; no Odoo required)
ruff check src tests      # lint

Containerized 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 -> delete

Troubleshooting

(c) 2026 onePhase - Proprietary. See LICENSE.