# mcp-odoo [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/erpipe-org/mcp-odoo  
**GitHub Stars:** 435  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-odoo

## Description
Odoo MCP: gated writes, multi-instance. Free hosted: ERPipe (mcp.erpipe.com)

## Tools
Capabilities this server exposes over MCP:

- **data_quality_report** — Run read-only data-quality checks on one Odoo model: duplicates, missing required values, orphaned references, format anomalies
- **diagnose_odoo_call** — Diagnose an Odoo model call without executing it
- **generate_json2_payload** — Build a JSON-2 request preview without network access
- **inspect_model_relationships** — Inspect model relationships and required field metadata
- **diagnose_access** — Diagnose ACL and record-rule visibility for an Odoo model
- **upgrade_risk_report** — Report Odoo upgrade and JSON-2 migration risks
- **analyze_upgrade_log** — Classify Odoo install/update log errors into a migration worklist (no_action / needs_review / needs_script) with fix suggestions
- **lookup_model_history** — Look up Odoo model rename/removal history by old or new model name (e.g. account.invoice -> account.move)
- **fit_gap_report** — Classify Odoo requirements into fit/gap implementation buckets
- **scan_addons_source** — Scan local Odoo addon source without importing addon code
- **build_domain** — Build a validated Odoo domain from structured conditions
- **business_pack_report** — Report expected modules, models, and safe discovery calls for a business pack
- **get_odoo_profile** — Read a bounded profile of the connected Odoo environment
- **schema_catalog** — Build and cache a bounded Odoo model schema catalog
- **health_check** — Report this MCP server's non-secret runtime safety posture
- **list_instances** — List configured Odoo instance names without credentials
- **list_models** — List Odoo models with optional name filtering
- **get_model_fields** — Get field metadata for a specific Odoo model
- **search_records** — Search Odoo records with read-only search_read; optional free-text `query` matches across name/ref/email-like fields
- **read_record** — Read a single Odoo record by model and ID
- **read_attachment** — Read an ir.attachment's metadata and size-capped base64 content
- **aggregate_records** — Aggregate Odoo records server-side using Postgres groupby/sum/count. Uses formatted_read_group on Odoo 19+ and read_group on earlier versions.
- **search_employee** — Search for employees by name
- **search_holidays** — Search for holidays within a date range
- **preview_write** — Preview create, write, or unlink without executing it
- **validate_write** — Validate a standard write payload against optional fields_get metadata
- **execute_approved_write** — Execute a previously previewed and confirmed standard write
- **chatter_post** — Post a chatter message on a mail.thread record. Default mode requires an approval token returned from a preview call; set MCP_CHATTER_DIRECT=1 to bypass and post immediately.
- **execute_method** — Execute a custom method on an Odoo model
- **index_knowledge** — Fetch a bounded slice of records and build a local BM25 knowledge index
- **search_knowledge** — Relevance-ranked local BM25 search over previously indexed records
- **knowledge_stats** — Report local knowledge index sizes and document budget
- **receivable_payable_aging** — Aged receivable/payable report bucketed by days overdue
- **accounting_health_summary** — Open receivable/payable item counts and draft invoice backlog
- **search_across_instances** — Read-only search fanned out across configured Odoo instances, merged and attributed
- **aggregate_across_instances** — Read-only aggregate fanned out across instances with combined grand totals
- **accounting_health_across_instances** — AR/AP aging fanned out across instances — the partner-network sweep
- **submit_async_task** — Run an allowlisted long-running read operation in the background
- **get_async_task** — Poll a background task's status and result
- **cancel_async_task** — Cancel a pending or running background task
- **list_async_tasks** — List recent background tasks newest-first

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "mcp-odoo": {
    "command": "uvx",
    "args": ["odoo-mcp"],
    "env": {
      "ODOO_MCP_ENABLE_WRITES": "",
      "ODOO_MCP_MAX_ATTACHMENT_BYTES": "",
      "ODOO_MCP_ALLOW_UNKNOWN_METHODS": "",
      "MCP_CHATTER_DIRECT": "",
      "ODOO_MCP_KNOWLEDGE_MAX_DOCS": "",
      "ODOO_MCP_ELICIT_WRITES": "",
      "ODOO_MCP_AUDIT_LOG": "",
      "ODOO_LOCALE": ""
    }
  }
}
```

**Requires environment variables:** `ODOO_MCP_ENABLE_WRITES`, `ODOO_MCP_MAX_ATTACHMENT_BYTES`, `ODOO_MCP_ALLOW_UNKNOWN_METHODS`, `MCP_CHATTER_DIRECT`, `ODOO_MCP_KNOWLEDGE_MAX_DOCS`, `ODOO_MCP_ELICIT_WRITES`, `ODOO_MCP_AUDIT_LOG`, `ODOO_LOCALE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mcp-odoo does

The mcp-odoo MCP server exposes an Odoo database through the Model Context Protocol. It is designed for local agents, IDE integrations, and automation that need to inspect business data, understand model structure, diagnose access problems, or perform controlled changes. The Python project runs locally or in Docker and can serve multiple named Odoo instances through configuration or environment settings.

Connections use the credentials already available for the Odoo account. The repository supports Odoo 16 and newer. It uses XML-RPC for Odoo 16–18 and supports External JSON-2 for Odoo 19+, including helpers for converting XML-RPC-shaped input into JSON-2 request details.

## How it works

Read calls cover model discovery, field metadata, bounded record searches, individual record reads, grouped aggregations, attachments, employees, and holiday records. When callers omit fields for common record reads, the server selects a narrower set of business-relevant fields. Domain construction and validation are available before making a model query.

The server also provides diagnostics for model calls and access rules, relationship inspection, model-history lookup, addon-source scanning, upgrade-risk analysis, and fit-gap classification. Local knowledge search first indexes a bounded record slice, then performs accent-insensitive BM25 searches without additional Odoo calls or sending indexed data to another service.

For changes, the workflow separates planning from execution. A caller can preview a create, write, or unlink request, validate it against live `fields_get` metadata, and execute it only with a same-session approval token, explicit confirmation, and `ODOO_MCP_ENABLE_WRITES=1`. Direct create, write, and unlink calls are blocked. Model methods are reviewed separately, with side-effect methods restricted by an exact allowlist unless unknown methods are explicitly enabled.

## Setup and configuration

Install and configure the local package with `uvx odoo-mcp --setup`. The repository can run over stdio or local HTTP/SSE, depending on the client. Configuration supports multiple named Odoo instances, with an optional instance selection on tool calls and instance-specific approval tokens and schema caches.

The server uses the Odoo connection details supplied during setup or through its configuration. Optional settings control write access, attachment size limits, chatter behavior, logging, audit output, locale handling, plugins, tool inclusion or exclusion, and rate limiting. The hosted ERPipe service is a separate managed option; this repository is the self-hosted Python server.

## Tools and capabilities

The mcp-odoo MCP server includes tools for:

- Listing models, reading field metadata, building bounded schema catalogs, and inspecting relationships.
- Searching and reading records, aggregating with Odoo group-by operations, and reading capped attachment content.
- Searching employees and holidays, producing accounting health and aged receivable/payable reports, and posting chatter messages.
- Diagnosing calls and access rules, checking upgrade risks, resolving renamed models, scanning addon source, and classifying implementation gaps.
- Indexing bounded record sets locally and searching them without further RPC requests.
- Previewing, validating, and executing approved writes, plus reviewing model methods before execution.

## Limitations and notes

Write support is disabled unless the write environment gate is enabled, and the approval flow still applies. Chatter posting normally uses the same approval-token process, although direct chatter mode can be enabled separately. Attachment content is size-capped, with the default limit set to 1 MiB.

Read operations are bounded, and local knowledge search only covers records included in its index. Access remains subject to the permissions of the configured Odoo credential. Multi-instance operation is available, but each instance must be configured and selected correctly. The repository includes a larger local tool surface than the separate hosted ERPipe service, so client and deployment behavior should be checked against the chosen transport.

_Full upstream README: https://allmcps.com/mcp/mcp-odoo/readme_

