Skip to content
Back to search

mcp-server-odoo

Model Context Protocol (MCP) server that enables AI assistants to securely interact with Odoo ERP systems through standardized resources and tools for data retrieval and manipulation.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ivnvxd/mcp-server-odoo with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ivnvxd/mcp-server-odoo'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

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

HTML

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

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Prerequisites

- Python 3.10 or higher - Access to an Odoo instance: - **Standard mode** (production): Version 16.0+ with the [Odoo MCP module](https://apps.odoo.com/apps/modules/19.0/mcp_server) installed - **YOLO mode** (testing/demos): Any Odoo version with XML-RPC enabled (no module required)

Install UV First

The MCP server runs on your **local computer** (where Claude Desktop is installed), not on your Odoo server. You need to install UV on your local machine:

<details> <summary>macOS/Linux</summary>

curl -LsSf https://astral.sh/uv/install.sh | sh

</details>

<details> <summary>Windows</summary>

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

</details>

After installation, restart your terminal to ensure UV is in your PATH.

Installing via MCP Settings (Recommended)

Add this configuration to your MCP settings:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here"
      }
    }
  }
}

<details> <summary>Claude Desktop</summary>

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}

</details>

<details> <summary>Claude Code</summary>

Add to `.mcp.json` in your project root:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}

Or use the CLI:

claude mcp add odoo \
  --env ODOO_URL=https://your-odoo-instance.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_DB=your-database-name \
  -- uvx mcp-server-odoo

</details>

<details> <summary>Cursor</summary>

Add to `~/.cursor/mcp.json`:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}

</details>

<details> <summary>VS Code (with GitHub Copilot)</summary>

Add to `.vscode/mcp.json` in your workspace:

{
  "servers": {
    "odoo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}

> **Note:** VS Code uses `"servers"` as the root key, not `"mcpServers"`. </details>

<details> <summary>Windsurf</summary>

Add to `~/.codeium/windsurf/mcp_config.json`:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}

</details>

<details> <summary>Zed</summary>

Add to `~/.config/zed/settings.json`:

{
  "context_servers": {
    "odoo": {
      "command": {
        "path": "uvx",
        "args": ["mcp-server-odoo"],
        "env": {
          "ODOO_URL": "https://your-odoo-instance.com",
          "ODOO_API_KEY": "your-api-key-here",
          "ODOO_DB": "your-database-name"
        }
      }
    }
  }
}

</details>

Alternative Installation Methods

<details> <summary>Using Docker</summary>

Run with Docker — no Python installation required:

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [

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 · 1,122 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP Server for Odoo
  2. [![CI](https://github.com/ivnvxd/mcp-server-odoo/actions/workflows/ci.yml/badge.svg)](https://github.com/ivnvxd/mcp-server-odoo/actions/workflows/ci.yml)
  3. [![codecov](https://codecov.io/gh/ivnvxd/mcp-server-odoo/branch/main/graph/badge.svg)](https://codecov.io/gh/ivnvxd/mcp-server-odoo)
  4. [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
  5. [![Checked with ty](https://img.shields.io/badge/checked%20with-ty-blue?labelColor=orange)](https://github.com/astral-sh/ty)
  6. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  7. [![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
  8. An MCP server that enables AI assistants like Claude to interact with Odoo ERP systems. Access business data, search records, create new entries, update existing data, and manage your Odoo instance through natural language.
  9. **Works with any Odoo instance!** Use [YOLO mode](#yolo-mode-developmenttesting-only-) for quick testing and demos with any standard Odoo installation. For enterprise security, access controls, and production use, install the [Odoo MCP module](https://apps.odoo.com/apps/modules/19.0/mcp_server).
  10. ## Features
  11. - 🔍 **Search and retrieve** any Odoo record (customers, products, invoices, etc.)
  12. - ✨ **Create new records** with field validation and permission checks
  13. - ✏️ **Update existing data** with smart field handling
  14. - 🗑️ **Delete records** respecting model-level permissions
  15. - 🔢 **Count records** matching specific criteria
  16. - 📋 **Inspect model fields** to understand data structure
  17. - 📊 **Server-side aggregation** — group, sum, and count without pulling raw rows
  18. - ⚡ **Workflow actions** — invoke public business methods (post invoice, confirm SO, etc.) via an opt-in escape hatch
  19. - 📎 **Binary & attachment resources** — fetch images, documents, and `ir.attachment` files via resource URIs
  20. - 👤 **Personalized session context** — the connected user, timezone, and company scope injected into the session instructions
  21. - 🔐 **Secure access** with API key or username/password authentication
  22. - 🎯 **Smart pagination** for large datasets
  23. - 🧠 **Smart field selection** — automatically picks the most relevant fields per model
  24. - 💬 **LLM-optimized output** with hierarchical text formatting
  25. - 🌍 **Multi-language support** — get responses in your preferred language
  26. - 🚀 **YOLO Mode** for quick access with any Odoo instance (no module required)
  27. ## Installation
  28. ### Prerequisites
  29. - Python 3.10 or higher
  30. - Access to an Odoo instance:
  31. - **Standard mode** (production): Version 16.0+ with the [Odoo MCP module](https://apps.odoo.com/apps/modules/19.0/mcp_server) installed
  32. - **YOLO mode** (testing/demos): Any Odoo version with XML-RPC enabled (no module required)
  33. ### Install UV First
  34. The MCP server runs on your **local computer** (where Claude Desktop is installed), not on your Odoo server. You need to install UV on your local machine:
  35. <details>
  36. <summary>macOS/Linux</summary>
  37. ```bash
  38. curl -LsSf https://astral.sh/uv/install.sh | sh
  39. ```
  40. </details>
  41. <details>
  42. <summary>Windows</summary>
  43. ```powershell
  44. powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  45. ```
  46. </details>
  47. After installation, restart your terminal to ensure UV is in your PATH.
  48. ### Installing via MCP Settings (Recommended)
  49. Add this configuration to your MCP settings:
  50. ```json
  51. {
  52. "mcpServers": {
  53. "odoo": {
  54. "command": "uvx",
  55. "args": ["mcp-server-odoo"],
  56. "env": {
  57. "ODOO_URL": "https://your-odoo-instance.com",
  58. "ODOO_API_KEY": "your-api-key-here"
  59. }
  60. }
  61. }
  62. }
  63. ```
  64. <details>
  65. <summary>Claude Desktop</summary>
  66. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
  67. ```json
  68. {
  69. "mcpServers": {
  70. "odoo": {
  71. "command": "uvx",
  72. "args": ["mcp-server-odoo"],
  73. "env": {
  74. "ODOO_URL": "https://your-odoo-instance.com",
  75. "ODOO_API_KEY": "your-api-key-here",
  76. "ODOO_DB": "your-database-name"
  77. }
  78. }
  79. }
  80. }
  81. ```
  82. </details>
  83. <details>
  84. <summary>Claude Code</summary>
  85. Add to `.mcp.json` in your project root:
  86. ```json
  87. {
  88. "mcpServers": {
  89. "odoo": {
  90. "command": "uvx",
  91. "args": ["mcp-server-odoo"],
  92. "env": {
  93. "ODOO_URL": "https://your-odoo-instance.com",
  94. "ODOO_API_KEY": "your-api-key-here",
  95. "ODOO_DB": "your-database-name"
  96. }
  97. }
  98. }
  99. }
  100. ```
  101. Or use the CLI:
  102. ```bash
  103. claude mcp add odoo \
  104. --env ODOO_URL=https://your-odoo-instance.com \
  105. --env ODOO_API_KEY=your-api-key-here \
  106. --env ODOO_DB=your-database-name \
  107. -- uvx mcp-server-odoo
  108. ```
  109. </details>
  110. <details>
  111. <summary>Cursor</summary>
  112. Add to `~/.cursor/mcp.json`:
  113. ```json
  114. {
  115. "mcpServers": {
  116. "odoo": {
  117. "command": "uvx",
  118. "args": ["mcp-server-odoo"],
  119. "env": {
  120. "ODOO_URL": "https://your-odoo-instance.com",
  121. "ODOO_API_KEY": "your-api-key-here",
  122. "ODOO_DB": "your-database-name"
  123. }
  124. }
  125. }
  126. }
  127. ```
  128. </details>
  129. <details>
  130. <summary>VS Code (with GitHub Copilot)</summary>
  131. Add to `.vscode/mcp.json` in your workspace:
  132. ```json
  133. {
  134. "servers": {
  135. "odoo": {
  136. "type": "stdio",
  137. "command": "uvx",
  138. "args": ["mcp-server-odoo"],
  139. "env": {
  140. "ODOO_URL": "https://your-odoo-instance.com",
  141. "ODOO_API_KEY": "your-api-key-here",
  142. "ODOO_DB": "your-database-name"
  143. }
  144. }
  145. }
  146. }
  147. ```
  148. > **Note:** VS Code uses `"servers"` as the root key, not `"mcpServers"`.
  149. </details>
  150. <details>
  151. <summary>Windsurf</summary>
  152. Add to `~/.codeium/windsurf/mcp_config.json`:
  153. ```json
  154. {
  155. "mcpServers": {
  156. "odoo": {
  157. "command": "uvx",
  158. "args": ["mcp-server-odoo"],
  159. "env": {
  160. "ODOO_URL": "https://your-odoo-instance.com",
  161. "ODOO_API_KEY": "your-api-key-here",
  162. "ODOO_DB": "your-database-name"
  163. }
  164. }
  165. }
  166. }
  167. ```
  168. </details>
  169. <details>
  170. <summary>Zed</summary>
  171. Add to `~/.config/zed/settings.json`:
  172. ```json
  173. {
  174. "context_servers": {
  175. "odoo": {
  176. "command": {
  177. "path": "uvx",
  178. "args": ["mcp-server-odoo"],
  179. "env": {
  180. "ODOO_URL": "https://your-odoo-instance.com",
  181. "ODOO_API_KEY": "your-api-key-here",
  182. "ODOO_DB": "your-database-name"
  183. }
  184. }
  185. }
  186. }
  187. }
  188. ```
  189. </details>
  190. ### Alternative Installation Methods
  191. <details>
  192. <summary>Using Docker</summary>
  193. Run with Docker — no Python installation required:
  194. ```json
  195. {
  196. "mcpServers": {
  197. "odoo": {
  198. "command": "docker",
  199. "args": [
  200. "run", "-i", "--rm",
  201. "-e", "ODOO_URL=http://host.docker.internal:8069",
  202. "-e", "ODOO_API_KEY=your-api-key-here",
  203. "ivnvxd/mcp-server-odoo"
  204. ]
  205. }
  206. }
  207. }
  208. ```
  209. > **Note:** Use `host.docker.internal` instead of `localhost` to connect to Odoo running on the host machine.
  210. For HTTP transport:
  211. ```bash
  212. docker run --rm -p 8000:8000 \
  213. -e ODOO_URL=http://host.docker.internal:8069 \
  214. -e ODOO_API_KEY=your-api-key-here \
  215. ivnvxd/mcp-server-odoo --transport streamable-http --host 0.0.0.0
  216. ```
  217. > ⚠️ **Security**: the HTTP transport has no built-in authentication — anyone who can reach the port gets Odoo access through the server's credentials. Publish the port only on trusted networks, or front it with an authenticating reverse proxy. See [Transport Options](#transport-options).
  218. The image is also available on GHCR: `ghcr.io/ivnvxd/mcp-server-odoo`
  219. </details>
  220. <details>
  221. <summary>Using pip</summary>
  222. ```bash
  223. # Install globally
  224. pip install mcp-server-odoo
  225. # Or use pipx for isolated environment
  226. pipx install mcp-server-odoo
  227. ```
  228. Then use `mcp-server-odoo` as the command in your MCP configuration.
  229. </details>
  230. <details>
  231. <summary>From source</summary>
  232. ```bash
  233. git clone https://github.com/ivnvxd/mcp-server-odoo.git
  234. cd mcp-server-odoo
  235. pip install -e .
  236. ```
  237. Then use the full path to the package in your MCP configuration.
  238. </details>
  239. ## Configuration
  240. ### Environment Variables
  241. The server requires the following environment variables:
  242. | Variable | Required | Description | Example |
  243. |----------|----------|-------------|---------|
  244. | `ODOO_URL` | Yes | Your Odoo instance URL | `https://mycompany.odoo.com` |
  245. | `ODOO_API_KEY` | Yes* | API key for authentication | `0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd` |
  246. | `ODOO_USER` | Yes* | Username (if not using API key) | `admin` |
  247. | `ODOO_PASSWORD` | Yes* | Password (if not using API key) | `admin` |
  248. | `ODOO_DB` | No | Database name (auto-detected if not set) | `mycompany` |
  249. | `ODOO_LOCALE` | No | Language/locale for Odoo responses | `es_ES`, `fr_FR`, `de_DE` |
  250. | `ODOO_ALLOWED_COMPANIES` | No | Comma-separated company IDs to scope all operations to (multi-company setups) | `1`, `1,3` |
  251. | `ODOO_YOLO` | No | YOLO mode - bypasses MCP security (⚠️ DEV ONLY) | `off`, `read`, `true` |
  252. | `ODOO_MCP_ENABLE_METHOD_CALLS` | No | Enable the `call_model_method` tool — requires `ODOO_YOLO=true` (⚠️ Dangerous, see [`call_model_method`](#call_model_method)) | `false`, `true` |
  253. | `ODOO_RPC_TRANSPORT` | No | RPC protocol in YOLO mode: `auto` (JSON-2 on Odoo 19 and later with an API key, else XML-RPC), `xmlrpc`, or `json2` for Odoo's JSON-2 API (Odoo 19 and later, API key only) | `auto`, `json2` |
  254. *Either `ODOO_API_KEY` or both `ODOO_USER` and `ODOO_PASSWORD` are required. In YOLO mode over XML-RPC, `ODOO_USER` is required even when using an API key. Over JSON-2 the API key alone is enough, because Odoo reads the user from the key.
  255. **Notes:**
  256. - If database listing is restricted on your server, you must specify `ODOO_DB`
  257. - API key authentication is recommended for better security
  258. - The server also loads environment variables from a `.env` file in the working directory
  259. - In standard mode, the server keeps each model's MCP permissions for 5 minutes. If you remove a permission in Odoo, the next call is refused at once, because the MCP module checks every call. If you grant a permission, it can take up to 5 minutes to work. Restart the server to apply it at once.
  260. **Multi-company scoping (`ODOO_ALLOWED_COMPANIES`):**
  261. In multi-company databases, the authenticated user's default company applies to
  262. every record the server creates, and record visibility spans all of the user's
  263. allowed companies. Setting `ODOO_ALLOWED_COMPANIES` injects
  264. `allowed_company_ids` into the context of every RPC call, so record rules,
  265. `env.company`, and create defaults are limited to the listed companies. A useful
  266. pattern is configuring one MCP server entry per company, sharing a single Odoo
  267. user:
  268. ```json
  269. {
  270. "mcpServers": {
  271. "odoo-company-a": {
  272. "command": "uvx",
  273. "args": ["mcp-server-odoo"],
  274. "env": { "ODOO_URL": "...", "ODOO_API_KEY": "...", "ODOO_ALLOWED_COMPANIES": "1" }
  275. },
  276. "odoo-company-b": {
  277. "command": "uvx",
  278. "args": ["mcp-server-odoo"],
  279. "env": { "ODOO_URL": "...", "ODOO_API_KEY": "...", "ODOO_ALLOWED_COMPANIES": "3" }
  280. }
  281. }
  282. }
  283. ```
  284. At startup, the server makes sure that each ID is one of the user's companies, and it does not
  285. start otherwise. If the user cannot read their own `res.users` record (standard mode without
  286. `res.users` enabled), the check is skipped with a warning, and Odoo refuses a foreign company on
  287. each call instead. The first ID is the active company: Odoo uses it for create defaults, and
  288. `get_current_context` and the session instructions show it. A call can narrow the scope to some of
  289. the listed companies, but never widen it.
  290. Note this is context-level scoping, not a security boundary: the credentials can
  291. still access every company the Odoo user is allowed to. For hard isolation,
  292. restrict the user's allowed companies in Odoo itself.
  293. #### Advanced Configuration
  294. | Variable | Default | Description |
  295. |----------|---------|-------------|
  296. | `ODOO_MCP_DEFAULT_LIMIT` | `25` | Default number of records returned per search |
  297. | `ODOO_MCP_MAX_LIMIT` | `100` | Maximum allowed record limit per request |
  298. | `ODOO_MCP_MAX_SMART_FIELDS` | `15` | Maximum fields returned by smart field selection |
  299. | `ODOO_MCP_LOG_LEVEL` | `INFO` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`) |
  300. | `ODOO_MCP_LOG_JSON` | `false` | Enable structured JSON log output |
  301. | `ODOO_MCP_LOG_FILE` | — | Path for rotating log file (10 MB, 5 backups) |
  302. | `ODOO_MCP_LOG_FORMAT` | — | Custom Python logging format string (default: `%(asctime)s - %(name)s - %(levelname)s - %(message)s`) |
  303. | `ODOO_MCP_SLOW_OPERATION_THRESHOLD_MS` | `1000` | Threshold in milliseconds above which an operation is logged as slow |
  304. | `ODOO_MCP_TRANSPORT` | `stdio` | Transport type (`stdio`, `streamable-http`) |
  305. | `ODOO_MCP_HOST` | `localhost` | Host to bind for HTTP transport |
  306. | `ODOO_MCP_PORT` | `8000` | Port to bind for HTTP transport |
  307. | `ODOO_MCP_ALLOWED_HOSTS` | — | Comma-separated `Host` headers to accept for HTTP transport (DNS-rebinding protection). Set when running `streamable-http` behind a reverse proxy that forwards an external host, e.g. `odoo.example.com,localhost`. IPv6 literals may be bracketed or bare (`[::1]:8000`, `::1`). **Unset, protection is only auto-enabled for a loopback bind** — binding any other host (e.g. `0.0.0.0`) runs with no `Host`/`Origin` validation at all. |
  308. | `ODOO_MCP_SESSION_IDLE_TIMEOUT` | — | Seconds of inactivity before a `streamable-http` session is closed and its server-side state freed, e.g. `600`. Unset means sessions never expire. |
  309. | `ODOO_MCP_MAX_BINARY_SIZE` | `52428800` | Maximum bytes returned by a single binary/attachment `resources/read`. Checked before the payload is fetched (for record fields, a `bin_size` probe on Odoo 19 and older, and the size of the backing attachment or a `field.size` count on Odoo 20; for attachments, the stored `file_size`), so an oversized read is refused with a clean error instead of being pulled into memory and re-encoded to base64 for the wire. On Odoo 20 a non-stored binary field (such as `avatar_128`), or a stored one whose attachment the user cannot read, is checked only after the fetch. |
  310. ### Transport Options
  311. The server supports multiple transport protocols for different use cases:
  312. #### 1. **stdio** (Default)
  313. Standard input/output transport - used by desktop AI applications like Claude Desktop.
  314. ```bash
  315. # Default transport - no additional configuration needed
  316. uvx mcp-server-odoo
  317. ```
  318. #### 2. **streamable-http**
  319. Standard HTTP transport for REST API-style access and remote connectivity.
  320. > ⚠️ **Security**: this transport has **no built-in client authentication**. Any client that can reach the port can use every tool and resource with the Odoo credentials the server holds — including writes in YOLO full-access mode. Keep the default `localhost` bind unless the network is trusted, and front the server with an authenticating reverse proxy (e.g. nginx with basic auth or OAuth) for remote access. The server logs a warning when binding a non-loopback host.
  321. ```bash
  322. # Run with HTTP transport (localhost only — safe default)
  323. uvx mcp-server-odoo --transport streamable-http --port 8000
  324. # Binding 0.0.0.0 exposes the server to the network — see the security note above
  325. uvx mcp-server-odoo --transport streamable-http --host 0.0.0.0 --port 8000
  326. # Or use environment variables
  327. export ODOO_MCP_TRANSPORT=streamable-http
  328. export ODOO_MCP_HOST=0.0.0.0
  329. export ODOO_MCP_PORT=8000
  330. uvx mcp-server-odoo
  331. ```
  332. The HTTP endpoint will be available at: `http://localhost:8000/mcp/`
  333. > **Note**: SSE (Server-Sent Events) transport has been deprecated in MCP protocol version 2025-03-26. Use streamable-http transport instead for HTTP-based communication.
  334. > **Note**: The HTTP transport refuses request bodies over 4 MiB with HTTP 413. It holds at most 10,000 open sessions and answers new ones with HTTP 503 beyond that. If `ODOO_MCP_SESSION_IDLE_TIMEOUT` is unset, sessions never expire, so set it for a long-running public server.
  335. <details>
  336. <summary>Running streamable-http transport for remote access</summary>
  337. ```json
  338. {
  339. "mcpServers": {
  340. "odoo-remote": {
  341. "command": "uvx",
  342. "args": ["mcp-server-odoo", "--transport", "streamable-http", "--port", "8080"],
  343. "env": {
  344. "ODOO_URL": "https://your-odoo-instance.com",
  345. "ODOO_API_KEY": "your-api-key-here",
  346. "ODOO_DB": "your-database-name"
  347. }
  348. }
  349. }
  350. }
  351. ```
  352. </details>
  353. ### Setting up Odoo
  354. 1. **Install the MCP module**:
  355. - Download the [mcp_server](https://apps.odoo.com/apps/modules/19.0/mcp_server) module
  356. - Install it in your Odoo instance
  357. - Navigate to Settings > MCP Server
  358. 2. **Enable models for MCP access**:
  359. - Go to Settings > MCP Server > Enabled Models
  360. - Add models you want to access (e.g., res.partner, product.product)
  361. - Configure permissions (read, write, create, delete) per model
  362. 3. **Generate an API key**:
  363. - Go to Settings > Users & Companies > Users
  364. - Select your user
  365. - Under the "API Keys" tab, create a new key
  366. - On Odoo 20, give the key the RPC scope (`rpc`). Odoo 20 accepts a key on its RPC routes only with that scope.
  367. - Copy the key for your MCP configuration
  368. 4. **Grant MCP access to the user**:
  369. - Add the user to the MCP User group in the access rights of the user
  370. - Recent module versions refuse API keys and password logins of users outside this group. The server then reports the reason from the module at startup.
  371. ### YOLO Mode (Development/Testing Only) ⚠️
  372. YOLO mode allows the MCP server to connect directly to any standard Odoo instance **without requiring the MCP module**. This mode bypasses all MCP security controls and is intended **ONLY for development, testing, and demos**.
  373. **🚨 WARNING: Never use YOLO mode in production environments!**
  374. #### YOLO Mode Levels
  375. 1. **Read-Only Mode** (`ODOO_YOLO=read`):
  376. - Allows all read operations (search, read, count)
  377. - Blocks all write operations (create, update, delete)
  378. - Safe for demos and testing
  379. - Shows "READ-ONLY" indicators in responses
  380. 2. **Full Access Mode** (`ODOO_YOLO=true`):
  381. - Allows ALL operations without restrictions
  382. - Full CRUD access to all models
  383. - **EXTREMELY DANGEROUS** - use only in isolated environments
  384. - Shows "FULL ACCESS" warnings in responses
  385. #### YOLO Mode Configuration
  386. <details>
  387. <summary>Read-Only YOLO Mode (safer for demos)</summary>
  388. ```json
  389. {
  390. "mcpServers": {
  391. "odoo-demo": {
  392. "command": "uvx",
  393. "args": ["mcp-server-odoo"],
  394. "env": {
  395. "ODOO_URL": "http://localhost:8069",
  396. "ODOO_USER": "admin",
  397. "ODOO_PASSWORD": "admin",
  398. "ODOO_DB": "demo",
  399. "ODOO_YOLO": "read"
  400. }
  401. }
  402. }
  403. }
  404. ```
  405. </details>
  406. <details>
  407. <summary>Full Access YOLO Mode (⚠️ use with extreme caution)</summary>
  408. ```json
  409. {
  410. "mcpServers": {
  411. "odoo-test": {
  412. "command": "uvx",
  413. "args": ["mcp-server-odoo"],
  414. "env": {
  415. "ODOO_URL": "http://localhost:8069",
  416. "ODOO_USER": "admin",
  417. "ODOO_PASSWORD": "admin",
  418. "ODOO_DB": "test",
  419. "ODOO_YOLO": "true"
  420. }
  421. }
  422. }
  423. }
  424. ```
  425. </details>
  426. #### When to Use YOLO Mode
  427. ✅ **Appropriate Uses:**
  428. - Local development with test data
  429. - Quick demos with non-sensitive data
  430. - Testing MCP clients before installing the MCP module
  431. - Prototyping in isolated environments
  432. ❌ **Never Use For:**
  433. - Production environments
  434. - Instances with real customer data
  435. - Shared development servers
  436. - Any environment with sensitive information
  437. #### YOLO Mode Security Notes
  438. - Connects directly to Odoo's standard XML-RPC endpoints, or to JSON-2 (`/json/2`) on Odoo 19 and later with an API key (see `ODOO_RPC_TRANSPORT`)
  439. - Bypasses all MCP access controls and model restrictions
  440. - No rate limiting is applied
  441. - All operations are logged but not restricted
  442. - Model listing shows 200+ models instead of just enabled ones
  443. - In full YOLO mode (`true`), the create, update and delete tools reach every model, scheduled actions (`ir.cron`) and server actions (`ir.actions.server`) included. `call_model_method` refuses to run them directly, but a changed action runs on its next schedule or trigger. This is the same power that an administrator has in the Odoo UI.
  444. ## Usage Examples
  445. Once configured, you can ask Claude:
  446. **Search & Retrieve:**
  447. - "Show me all customers from Spain"
  448. - "Find products with stock below 10 units"
  449. - "List today's sales orders over $1000"
  450. - "Search for unpaid invoices from last month"
  451. - "Count how many active employees we have"
  452. - "Show me the contact information for Microsoft"
  453. **Create & Manage:**
  454. - "Create a new customer contact for Acme Corporation"
  455. - "Add a new product called 'Premium Widget' with price $99.99"
  456. - "Create a calendar event for tomorrow at 2 PM"
  457. - "Update the phone number for customer John Doe to +1-555-0123"
  458. - "Change the status of order SO/2024/001 to confirmed"
  459. - "Delete the test contact we created earlier"
  460. ## Available Tools
  461. ### `search_records`
  462. Search for records in any Odoo model with filters.
  463. ```json
  464. {
  465. "model": "res.partner",
  466. "domain": [["is_company", "=", true], ["country_id.code", "=", "ES"]],
  467. "fields": ["name", "email", "phone"],
  468. "limit": 10
  469. }
  470. ```
  471. **Field Selection Options:**
  472. - Omit `fields` or set to `null`: Returns smart selection of common fields
  473. - Specify field list: Returns only those specific fields
  474. - An empty list `[]` is treated like `null` (smart defaults)
  475. - Use `["__all__"]`: Returns all fields (use with caution) — credential-like fields are withheld and listed in the response's `note`; request them explicitly by name if needed
  476. ### `get_record`
  477. Retrieve a specific record by ID.
  478. ```json
  479. {
  480. "model": "res.partner",
  481. "record_id": 42,
  482. "fields": ["name", "email", "street", "city"]
  483. }
  484. ```
  485. **Field Selection Options:**
  486. - Omit `fields` or set to `null`: Returns smart selection of common fields with metadata
  487. - Specify field list: Returns only those specific fields
  488. - An empty list `[]` is treated like `null` (smart defaults)
  489. - Use `["__all__"]`: Returns all fields — credential-like fields are withheld and noted in the response metadata; request them explicitly by name if needed
  490. Responses also include `related_summaries`: display names for one2many/many2many collections holding at most 5 ids, so small relations are readable without extra lookups.
  491. ### `get_fields`
  492. Describe a model's fields — type, label, required/readonly, relation target, and selection options. Use it to discover a model's schema before reading or writing records. Omit `attributes` for the curated default set (`type`, `string`, `required`, `readonly`, `relation`, `selection`); an explicit list replaces the curated set — include the defaults in your list if you still need them (e.g. `["type", "string", "help", "store"]`). Omit `field_names` for a short view: the 60 most relevant value fields, plus every one2many, many2many, file and HTML field, with selection lists cut at 20 values. The response then includes `omitted`, the number of fields left out, and a `note`. Pass `["__all__"]` for every field, or name the fields you need. These two forms do not cut selection lists. An empty list `[]` for either parameter is treated like omitting it.
  493. ```json
  494. {
  495. "model": "res.partner",
  496. "field_names": ["name", "email", "parent_id"]
  497. }
  498. ```
  499. ### `get_current_context`
  500. Return the current session context: the connected user, their timezone, the active company plus any other allowed companies, and UTC datetime-handling guidance. Useful when unsure which user or company a request runs as, or how to interpret datetimes. Spec-compliant clients also receive this context through the `initialize` response instructions.
  501. ```json
  502. {}
  503. ```
  504. ### `list_models`
  505. List all models enabled for MCP access.
  506. ```json
  507. {}
  508. ```
  509. ### `list_resource_templates`
  510. List available resource URI templates and their patterns.
  511. ```json
  512. {}
  513. ```
  514. ### `create_record`
  515. Create a new record in Odoo.
  516. ```json
  517. {
  518. "model": "res.partner",
  519. "values": {
  520. "name": "New Customer",
  521. "email": "customer@example.com",
  522. "is_company": true
  523. }
  524. }
  525. ```
  526. ### `create_records`
  527. Create several records of one model in one call. The call accepts at most 100 records. It is one transaction: either every record is created or none.
  528. ```json
  529. {
  530. "model": "res.partner",
  531. "records": [
  532. {"name": "Customer A", "email": "a@example.com"},
  533. {"name": "Customer B", "email": "b@example.com"}
  534. ]
  535. }
  536. ```
  537. ### `update_record`
  538. Update an existing record.
  539. ```json
  540. {
  541. "model": "res.partner",
  542. "record_id": 42,
  543. "values": {
  544. "phone": "+1234567890",
  545. "website": "https://example.com"
  546. }
  547. }
  548. ```
  549. ### `update_records`
  550. Update several records of one model in one call, with at most 100 distinct records. If any ID does not exist, nothing is written. Archived records can be updated, for example to unarchive them with `"active": true`. Use one of two forms.
  551. The same values on every record, on any Odoo version:
  552. ```json
  553. {
  554. "model": "res.partner",
  555. "record_ids": [42, 43, 44],
  556. "values": {
  557. "category_id": [[4, 7]]
  558. }
  559. }
  560. ```
  561. Different values per record, in one transaction, on Odoo 19 and later:
  562. ```json
  563. {
  564. "model": "res.partner",
  565. "updates": [
  566. {"id": 42, "values": {"phone": "+1 555 0100"}},
  567. {"id": 43, "values": {"phone": "+1 555 0101"}}
  568. ]
  569. }
  570. ```
  571. The second form uses Odoo's `web_save_multi`. In standard mode, the Odoo MCP module must allow that method.
  572. ### `delete_record`
  573. Delete a record from Odoo.
  574. ```json
  575. {
  576. "model": "res.partner",
  577. "record_id": 42
  578. }
  579. ```
  580. ### `read_attachment`
  581. Read a file: an attachment or a binary field such as an image. Pass exactly one of `uri` (an `odoo://attachment/{id}` or `odoo://{model}/record/{id}/{field}` URI from a tool result) or `attachment_id`. The result depends on the file:
  582. - text files: their text, up to 100,000 characters
  583. - PDF and Office files: the text Odoo extracted from them (Odoo extracts PDF text only with the `attachment_indexation` module)
  584. - PNG, JPEG, GIF and WebP images up to 256 KB: the image itself
  585. - anything else: a download link for a person logged in to Odoo
  586. ```json
  587. {
  588. "uri": "odoo://res.partner/record/42/image_1920"
  589. }
  590. ```
  591. Most chat clients never read MCP resources by themselves, so this tool is the way for the model to see a file.
  592. ### `list_record_attachments`
  593. List the files attached to a record, newest first, with name, mimetype, size, date and an `odoo://attachment/{id}` URI each. Files behind binary fields such as `image_1920` are not listed, because `get_record` returns those as URIs.
  594. ```json
  595. {
  596. "model": "res.partner",
  597. "record_id": 42
  598. }
  599. ```
  600. ### `upload_attachment`
  601. Attach a file to a record. `data` is the file as plain base64, at most about 2.9 MB after decoding. Odoo detects the mimetype when `mimetype` is not given. The result carries the new attachment's ID and its `odoo://attachment/{id}` URI. To show the file in the chatter, pass the ID to `post_message` as `attachment_ids`.
  602. ```json
  603. {
  604. "model": "res.partner",
  605. "record_id": 42,
  606. "name": "contract.pdf",
  607. "data": "JVBERi0xLjQK...",
  608. "mimetype": "application/pdf"
  609. }
  610. ```
  611. In standard mode, the user needs write access on the record's model and create access on `ir.attachment`.
  612. ### `post_message`
  613. Post a message to a record's chatter (`mail.thread`). `subtype="note"` (default) is an internal log; `subtype="comment"` notifies followers. Set `body_is_html=true` for HTML markup. Optional `subject` sets a message subject line; optional `partner_ids` and `attachment_ids` reference existing partners and attachments.
  614. ```json
  615. {
  616. "model": "res.partner",
  617. "record_id": 42,
  618. "body": "Called customer, will follow up Tuesday"
  619. }
  620. ```
  621. ```json
  622. {
  623. "model": "sale.order",
  624. "record_id": 17,
  625. "body": "<p>Shipping confirmed for Monday</p>",
  626. "subtype": "comment",
  627. "body_is_html": true
  628. }
  629. ```
  630. ### `aggregate_records`
  631. Server-side aggregation. Use this whenever the question is "totals/counts/groupings" rather than "list of records" — it pushes the work down to PostgreSQL instead of pulling raw rows. Dispatches to `formatted_read_group` on Odoo 19+ (the new dedicated method) and falls back to `read_group` with response normalization on older versions. Callers see a consistent response shape on every supported version. When `aggregates` is omitted, defaults to `["__count"]` so each group always carries a count. When more groups exist beyond the requested page, the response sets `has_more: true` and a `next_hint` with the follow-up offset.
  632. ```json
  633. {
  634. "model": "sale.order",
  635. "groupby": ["date_order:month"],
  636. "aggregates": ["amount_total:sum"],
  637. "domain": [["state", "in", ["sale", "done"]]]
  638. }
  639. ```
  640. ```json
  641. {
  642. "model": "res.partner",
  643. "groupby": ["country_id"]
  644. }
  645. ```
  646. ### `call_model_method`
  647. Generic XML-RPC `execute_kw` escape hatch — invokes public **business** methods, for workflow actions not covered by CRUD (post invoice, confirm sale order, validate picking, etc.). Available **only** when both `ODOO_YOLO=true` (full YOLO) and `ODOO_MCP_ENABLE_METHOD_CALLS=true` are set; otherwise the tool is not registered. Only public ASCII Python identifiers are accepted as method names — dotted, dashed, whitespace, non-ASCII, and `_`-prefixed names are rejected.
  648. Some calls are blocked for safety even in full YOLO mode:
  649. - **`ir.actions.*` / `ir.cron` models** — their methods run with elevated privileges (server actions, scheduled jobs)
  650. - **`run` / `method_direct_trigger`** on any model — same escalation risk via proxies
  651. - **ORM CRUD/data-access primitives** (`create`, `write`, `unlink`, `read`, `search*`, `copy`, `sudo`, ...) — use the dedicated tools instead
  652. - **`web_*` methods** — the web-client data-access family
  653. List results are truncated to 100 items.
  654. Over JSON-2 (Odoo 19 and later in YOLO mode with an API key, or `ODOO_RPC_TRANSPORT=json2`), Odoo takes named arguments only. `arguments` can then hold only the record IDs, as its first item. Pass every other argument in `keyword_arguments`, by its parameter name, for example `{"partner_ids": [3]}`.
  655. > [!WARNING]
  656. > This tool can still invoke destructive workflow methods (e.g. `button_draft`, `action_cancel`, `toggle_active`, custom methods). Enable only in trusted environments where you accept the blast radius. Odoo's record rules and ACLs still apply for the authenticated user.
  657. ```json
  658. {
  659. "model": "account.move",
  660. "method": "action_post",
  661. "arguments": [[42]]
  662. }
  663. ```
  664. ```json
  665. {
  666. "model": "sale.order",
  667. "method": "action_confirm",
  668. "arguments": [[7]],
  669. "keyword_arguments": {"context": {"lang": "en_US"}}
  670. }
  671. ```
  672. ### Smart Field Selection
  673. When you omit the `fields` parameter (or set it to `null`), the server automatically selects the most relevant fields for each model using a scoring algorithm:
  674. - **Essential fields** like `id`, `name`, `display_name`, and `active` are always included
  675. - **Business-relevant fields** (state, amount, email, phone, partner, etc.) are prioritized
  676. - **Technical fields** (message threads, activity tracking, website metadata) are excluded
  677. - **Expensive fields** (binary, HTML, large text) are skipped; computed non-stored fields are deprioritized
  678. - **Credential-like fields** (names ending in `*password`, `*_pass` like `smtp_pass`, `passwd`, `*secret`, `*_token`, `*apikey`, or a `*_key` compound such as `api_key`/`secret_key`) are excluded from smart defaults and withheld from `["__all__"]` reads with an explanatory note — requesting such a field explicitly by name still returns it
  679. The default limit is 15 fields per request. Responses include metadata showing which fields were returned and how many total fields are available. You can adjust the limit with `ODOO_MCP_MAX_SMART_FIELDS` or bypass it entirely with `fields: ["__all__"]`.
  680. If Odoo refuses a field to the connected user, for example an accounting total on a contact for a user without accounting rights, a smart-default or `["__all__"]` read leaves that field out. The response lists it in `skipped_fields` and in the note. A read with an explicit field list still fails with the access error.
  681. ### Per-call context
  682. `search_records`, `get_record`, `aggregate_records`, `create_record`, `create_records`, `update_record` and `update_records` take an optional `context` object. It accepts four keys:
  683. | Key | Effect |
  684. |---|---|
  685. | `allowed_company_ids` | The companies of the call. The first one is the active company, so company-dependent fields such as `standard_price` read and write its value. |
  686. | `lang` | The language of labels and translated values. A language that Odoo has not installed is refused. On Odoo 16 and 17 the server checks this itself; in standard mode that needs `res.partner` or `res.lang` enabled for MCP, otherwise only `en_US` is accepted. |
  687. | `tz` | The timezone of the call. |
  688. | `active_test` | `false` includes archived records in searches. |
  689. The tool refuses any other key and names it. Each company must be one of the user's companies, and one of `ODOO_ALLOWED_COMPANIES` when that is set. The context applies to the search, the count, the read, the existence check and the read-back after a write.
  690. ```json
  691. {
  692. "model": "product.product",
  693. "record_id": 42,
  694. "values": {"standard_price": 12.5},
  695. "context": {"allowed_company_ids": [5]}
  696. }
  697. ```
  698. ## Resources
  699. The server also provides direct access to Odoo data through resource URIs:
  700. | URI Pattern | Description |
  701. |------------|-------------|
  702. | `odoo://{model}/record/{id}` | Retrieve a specific record by ID |
  703. | `odoo://{model}/search` | Search records with default settings (the first `ODOO_MCP_DEFAULT_LIMIT` records, 25 by default) |
  704. | `odoo://{model}/count` | Count all records in a model |
  705. | `odoo://{model}/fields` | Get field definitions and metadata for a model |
  706. | `odoo://{model}/record/{id}/{field}` | Fetch a binary/image field from a record, served with the correct mimeType |
  707. | `odoo://attachment/{id}` | Fetch an `ir.attachment` by ID (url-type attachments return their URL as text) |
  708. **Examples:**
  709. - `odoo://res.partner/record/1` — Get partner with ID 1
  710. - `odoo://product.product/search` — List the first products (`ODOO_MCP_DEFAULT_LIMIT`, 25 by default)
  711. - `odoo://res.partner/count` — Count all partners
  712. - `odoo://product.product/fields` — Show all fields for products
  713. - `odoo://res.partner/record/1/image_128` — Get partner 1's avatar image
  714. - `odoo://attachment/42` — Download attachment 42
  715. Populated binary fields in `get_record`/`search_records` results are returned as these resource URIs instead of inline base64 — read the URI to retrieve the actual bytes. The bytes come from `resources/read`, or from the `read_attachment` tool, which returns text files (up to 1 MB) and PNG, JPEG, GIF and WebP images (up to 256 KB) inline for clients that do not read resources.
  716. Record and search resource reads withhold credential-like fields the same way the tools' bulk reads do — to read such a field, request it explicitly by name via the tools' `fields` parameter.
  717. Binary and attachment reads are served whole, up to `ODOO_MCP_MAX_BINARY_SIZE` (default 50 MB). The size is checked before the payload is fetched, so an oversized field or attachment is refused with a clean error rather than buffered into a correspondingly large response. On Odoo 20 a non-stored binary field, or a stored one whose attachment the user cannot read, is checked only after the fetch.
  718. > **Note:** Resource URIs don't support query parameters (like `?domain=...`). For filtering, pagination, and field selection, use the `search_records` tool instead.
  719. ## How It Works
  720. ```
  721. AI Assistant (Claude, Copilot, etc.)
  722. ↓ MCP Protocol (stdio or HTTP)
  723. mcp-server-odoo
  724. ↓ XML-RPC, or JSON-2 on Odoo 19+ in YOLO mode
  725. Odoo Instance
  726. ```
  727. The server translates MCP tool calls into Odoo XML-RPC requests, or JSON-2 requests on Odoo 19 and later in YOLO mode with an API key. It handles authentication, access control, field selection, data formatting, and error handling — presenting Odoo data in an LLM-friendly hierarchical text format.
  728. ## Security
  729. - Always use HTTPS in production environments
  730. - Keep your API keys secure and rotate them regularly
  731. - Configure model access carefully - only enable necessary models
  732. - The MCP module respects Odoo's built-in access rights and record rules
  733. - Each API key is linked to a specific user with their permissions
  734. ### How standard mode applies the model allowlist
  735. In standard mode, the server checks the MCP module's model allowlist before each call. It also checks the models that a call reaches through another model:
  736. - Nested x2many commands in `values`. A create command (`[0, 0, {...}]`) needs create access on the related model, an update (`[1, id, {...}]`) needs write access, and a delete (`[2, id]`) needs delete access.
  737. - On a one2many field, a link (`[4, id]`) needs write access on the related model. A removal (`[3, id]`, `[5]` or `[6, 0, ids]`) needs write and delete access, because Odoo deletes the related records when the inverse field cascades. If the related model does not allow deletes, update the link field of the related record instead.
  738. - Attachments, messages, emails, followers, activities, tracking values and notifications. Reads return only the rows of models that allow reads. Creating, changing, moving or deleting a row needs write access on the model that it belongs to, also through a nested command such as `message_ids: [[1, id, {...}]]`.
  739. - To create an activity, the server reads `ir.model` to find the model of `res_model_id`, so `ir.model` must be readable for MCP.
  740. - Reads through a relation. A condition on a dotted path such as `user_ids.groups_id.name`, an `any` or `not any` condition, a name condition on an x2many field, and an `order` through a relation need read access on each related model that they pass through. Grouping by an x2many field needs read access on its related model. A condition on a many2one by name (`country_id ilike Germany`) stays allowed, but a dotted path into it (`country_id.code = DE`) needs read access on the related model.
  741. These checks do not cover writable related fields and `_inherits` parents. For example, a write of `email` on a user also writes to its partner. In the same way, the name, email, phone and address of a company are fields of its partner record: if `res.partner` allows writes, they can be changed there even when `res.company` is read-only. A many2one value counts as part of the record that holds it: its name is returned on reads and groupings, and you can set it to a record of a model that is not enabled. The same applies to a many2many link (`[4, id]`, `[3, id]`, `[6, 0, ids]`). Odoo's own access rights and record rules apply to every call.
  742. ## Troubleshooting
  743. <details>
  744. <summary>Connection Issues</summary>
  745. If you're getting connection errors:
  746. 1. Verify your Odoo URL is correct and accessible
  747. 2. Check that the MCP module is installed: visit `https://your-odoo.com/mcp/health`
  748. 3. Ensure your firewall allows connections to Odoo
  749. </details>
  750. <details>
  751. <summary>Authentication Errors</summary>
  752. If authentication fails:
  753. 1. Verify your API key is active in Odoo
  754. 2. Check that the user has appropriate permissions
  755. 3. Try regenerating the API key
  756. 4. For username/password auth, ensure 2FA is not enabled
  757. 5. On Odoo 20, make sure that the API key has the `rpc` scope
  758. 6. In standard mode, make sure that the user is in the MCP User group
  759. </details>
  760. <details>
  761. <summary>Model Access Errors</summary>
  762. If you can't access certain models:
  763. 1. Go to Settings > MCP Server > Enabled Models in Odoo
  764. 2. Ensure the model is in the list and has appropriate permissions
  765. 3. Check that your user has access to that model in Odoo's security settings
  766. </details>
  767. <details>
  768. <summary>"spawn uvx ENOENT" Error</summary>
  769. This error means UV is not installed or not in your PATH:
  770. **Solution 1: Install UV** (see Installation section above)
  771. **Solution 2: macOS PATH Issue**
  772. Claude Desktop on macOS doesn't inherit your shell's PATH. Try:
  773. 1. Quit Claude Desktop completely (Cmd+Q)
  774. 2. Open Terminal
  775. 3. Launch Claude from Terminal:
  776. ```bash
  777. open -a "Claude"
  778. ```
  779. **Solution 3: Use Full Path**
  780. Find UV location and use full path:
  781. ```bash
  782. which uvx
  783. # Example output: /Users/yourname/.local/bin/uvx
  784. ```
  785. Then update your config:
  786. ```json
  787. {
  788. "command": "/Users/yourname/.local/bin/uvx",
  789. "args": ["mcp-server-odoo"]
  790. }
  791. ```
  792. </details>
  793. <details>
  794. <summary>Database Configuration Issues</summary>
  795. If you see "Access Denied" when listing databases:
  796. - This is normal - some Odoo instances restrict database listing for security
  797. - Make sure to specify `ODOO_DB` in your configuration
  798. - The server will use your specified database without validation
  799. Example configuration:
  800. ```json
  801. {
  802. "env": {
  803. "ODOO_URL": "https://your-odoo.com",
  804. "ODOO_API_KEY": "your-key",
  805. "ODOO_DB": "your-database-name"
  806. }
  807. }
  808. ```
  809. Note: `ODOO_DB` is required if database listing is restricted on your server.
  810. </details>
  811. <details>
  812. <summary>"SSL: CERTIFICATE_VERIFY_FAILED" Error</summary>
  813. This error occurs when Python cannot verify SSL certificates, often on macOS or corporate networks.
  814. **Solution**: Add SSL certificate path to your environment configuration:
  815. ```json
  816. {
  817. "env": {
  818. "ODOO_URL": "https://your-odoo.com",
  819. "ODOO_API_KEY": "your-key",
  820. "SSL_CERT_FILE": "/etc/ssl/cert.pem"
  821. }
  822. }
  823. ```
  824. This tells Python where to find the system's SSL certificate bundle for HTTPS connections. The path `/etc/ssl/cert.pem` is the standard location on most systems.
  825. </details>
  826. <details>
  827. <summary>Debug Mode</summary>
  828. Enable debug logging for more information:
  829. ```json
  830. {
  831. "env": {
  832. "ODOO_URL": "https://your-odoo.com",
  833. "ODOO_API_KEY": "your-key",
  834. "ODOO_MCP_LOG_LEVEL": "DEBUG"
  835. }
  836. }
  837. ```
  838. </details>
  839. ## Development
  840. <details>
  841. <summary>Running from source</summary>
  842. ```bash
  843. # Clone the repository
  844. git clone https://github.com/ivnvxd/mcp-server-odoo.git
  845. cd mcp-server-odoo
  846. # Install in development mode
  847. pip install -e ".[dev]"
  848. # Run tests
  849. pytest --cov
  850. # Run the server
  851. python -m mcp_server_odoo
  852. # Check version
  853. python -m mcp_server_odoo --version
  854. ```
  855. </details>
  856. <details>
  857. <summary>Testing with MCP Inspector</summary>
  858. ```bash
  859. # Using uvx
  860. npx @modelcontextprotocol/inspector uvx mcp-server-odoo
  861. # Using local installation
  862. npx @modelcontextprotocol/inspector python -m mcp_server_odoo
  863. ```
  864. </details>
  865. ## Testing
  866. ### Running Tests
  867. ```bash
  868. # Unit tests (no Odoo needed)
  869. uv run pytest -m "not yolo and not mcp" --cov
  870. # YOLO integration tests (vanilla Odoo, no MCP module)
  871. uv run pytest -m "yolo" -v
  872. # MCP integration tests (Odoo + MCP module installed)
  873. uv run pytest -m "mcp" -v
  874. # All tests
  875. uv run pytest --cov
  876. # Run specific test categories
  877. uv run pytest tests/test_tools.py -v
  878. uv run pytest tests/test_server_foundation.py -v
  879. ```
  880. ## License
  881. This project is licensed under the Mozilla Public License 2.0 (MPL-2.0) - see the [LICENSE](LICENSE) file for details.
  882. ## Contributing
  883. Contributions are very welcome! Please see the [CONTRIBUTING](CONTRIBUTING.md) guide for details.
  884. ## Support
  885. Thank you for using this project! If you find it helpful and would like to support my work, kindly consider buying me a coffee. Your support is greatly appreciated!
  886. <a href="https://www.buymeacoffee.com/ivnvxd" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
  887. And do not forget to give the project a star if you like it! :star:

Ratings and comments

Sign in to rate this skill.

Sign in

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