DOCSEARCHbyAlgolia
Submit Docs

odoo-mcp

repository·main·Indexed 17 days ago

https://github.com/tuanle96/mcp-odoo

A Model Context Protocol (MCP) server enabling AI agents to interact with Odoo 16+ databases. It provides 41 tools with gated writes and multi-instance support without requiring Odoo-side installation. Compatible with CrewAI, Cursor, LangGraph, n8n, and OpenAI Agents SDK via stdio or streamable-http transports.

Tokens
53.6K
Snippets
131
Records
229
Agent score
62%

What's inside odoo-mcp

  1. Overview of Odoo MCP

    main

    Odoo MCP is a Model Context Protocol (MCP) server that provides an AI-ready layer for any Odoo 16+ instance (Community or Enterprise). It allows AI agents (like Claude, GPT, or Gemini) to interact with Odoo databases using existing credentials without requiring any App Store modules or administrative changes on the Odoo side.

    Key capabilities include:

    • 41 MCP tools: For reading records, inspecting schemas, scanning addons, and performing diagnostics.
    • Safe Writes: A gated workflow for create, write, and unlink operations that requires approval tokens and validation.
    • Multi-instance support: A single server can manage multiple named Odoo instances simultaneously.
    • Odoo 16-19 Compatibility: Supports XML-RPC for older versions and is ready for Odoo 19+ via External JSON-2.
    • Advanced Features: Includes field-level ACLs, cross-instance queries, background tasks, and local-first knowledge search.

  2. Use the Odoo data-quality gate skill

    main

    The odoo-data-quality-gate skill is used to audit an Odoo database for issues like duplicates, missing required values, orphaned references, and format anomalies. It is designed to provide evidence-based findings before any data modification occurs.

    When to use:

    • When a user asks to "check data quality", "clean up data", "prepare for migration", or "find duplicates".
    • When aggregate answers from the AI appear suspicious.
    • To drive remediation through a gated write workflow that requires human approval for every batch.

  3. Available odoo-mcp Agent Skills

    main

    The erpipe-org/mcp-odoo repository provides several specialized workflow skills. Each skill leverages specific odoo-mcp tools to drive business processes.

    SkillPurposeKey odoo-mcp tools
    odoo-data-quality-gateEvidence-first data audit and gated remediationdata_quality_report, diagnose_access, write gate
    odoo-migration-copilotVersion-upgrade worklists (16→19/20), log triage, JSON-2 prepscan_addons_source, analyze_upgrade_log, upgrade_risk_report, lookup_model_history, generate_json2_payload
    odoo-month-end-closeMonth-end close with human sign-off per postingaccounting_health_summary, receivable_payable_aging, aggregate_records, write gate, chatter_post
    odoo-agency-fleet-reviewMulti-client fleet status for agencies/partnerslist_instances, *_across_instances, async tasks

  4. Configure Odoo Transport Protocols

    main

    The transport protocol used by the odoo_mcp.odoo_client depends on your Odoo version and configuration preference.

    Odoo VersionRecommended TransportNotes
    16.0, 17.0, 18.0XML-RPCDefault compatibility path.
    19.0JSON-2 or XML-RPCJSON-2 is opt-in via ODOO_TRANSPORT=json2.

    JSON-2 Specifics:

    • Uses bearer authentication and named JSON arguments.
    • To pass the database name via headers, set ODOO_JSON2_DATABASE_HEADER=1 (uses X-Odoo-Database).

  5. Configure Multi-Instance Routing

    main

    A single Odoo MCP server can manage multiple Odoo instances. Configuration is resolved in this order: ODOO_CONFIG_FILE $\rightarrow$ standard config paths $\rightarrow$ legacy environment variables.

    Routing Mechanics:

    • Tool Parameter: Tools accept an optional instance parameter to target a specific Odoo connection.
    • Isolation: Each instance is self-contained. Credentials and transport settings for one instance never fall back to environment variables or inherit from other instances.
    • Security: Approval tokens are hashed with the instance name, meaning a token for instance_a cannot be used to execute a write on instance_b.
    • Schema Caching: Caches are partitioned as {instance}:{model} to prevent metadata leakage between databases.
    • Discovery: The list_instances tool exposes names, URLs, databases, and transports (but never credentials).

  6. Understand the limitations of Field ACL

    main

    When implementing Field ACL, be aware of the following constraints:

    • Curated tools are exempt: Tools like search_employee and search_holidays use fixed, curated projections of non-sensitive fields. They do not use the redaction path and cannot be modified by Field ACL. To protect sensitive employee data, use read_record or search_records instead.
    • Attachment payloads are not redacted: Field ACL applies to attachment metadata only. It does not parse or redact the actual content/bytes inside an attachment. Do not use it to hide secrets embedded within files.
    • Writes are not affected: Field ACL is a read-path control. It does not prevent writing to a field. If the Odoo credential allows it and the write execution workflow is enabled, a field hidden from reads can still be written.
    • Server-side only: This protection only applies to requests made through the MCP server. Direct connections to Odoo using the same credentials are unaffected.

  7. Choose between local and hosted OpenAI Agent variants

    main

    Depending on your deployment architecture, choose one of the following two implementation patterns:

    • Local Development (odoo_agent.py): Use MCPServerStreamableHttp when your agent process connects to a local MCP server. This is suitable for local development or private networks.
    • Deployed/Public (hosted_odoo_agent.py): Use HostedMCPTool when OpenAI's model side needs to connect to your public MCP server. This is required for deployed servers and works with OpenAI models on the Responses API only.

  8. Architecture and Layering for Adding Tools

    main

    The odoo-mcp project follows a strict layering pattern enforced by .importlinter. When adding a new tool, you must separate the business logic from the MCP registration surface.

    • Core Layer (Pure Logic): Contains the actual Odoo interaction logic. Files like odoo_client.py or tool_helpers.py must never import the MCP surface.
    • Surface Layer (MCP Tools): Contains thin wrappers that register tools with the MCP server. These files (e.g., tools_read.py, tools_write.py) import mcp from server_core and use the @mcp.tool decorator.
    • Aggregation Layer: The server.py file acts as a pure re-export point. Importing from odoo_mcp.server registers all tools.

  9. Understand multi-client behavior in odoo-mcp HTTP mode

    main

    When running odoo-mcp in HTTP mode, certain resources are process-global rather than session-specific. If multiple clients (e.g., different users or different AI agents) connect to the same running HTTP server process, they will share access to:

    • Background task results: Results from list_async_tasks and get_async_task are visible to all clients connected to that process.
    • Local knowledge indexes: Indexed snippets are shared across all clients on the same process.

    Since all clients already share the same Odoo credentials, this behavior is intended for convenience. However, if you require strict isolation between different operators, you should run separate server processes for each user.

  10. Compare Odoo MCP with hosted ERPipe

    main

    You can choose between running the local Python server (odoo-mcp) or using the managed cloud service (ERPipe).

    Featureodoo-mcp (Local)ERPipe (Hosted)
    Run whereYour laptop / Docker / CICloudflare (managed)
    Installuvx odoo-mcp --setupSign up at mcp.erpipe.com
    MCP URLstdio or local HTTPhttps://mcp.erpipe.com/mcp
    ClientsClaude Code, Cursor, local agentsChatGPT (primary), Claude, Cursor, etc.
    Tool surface41 tools + 11 prompts37 tools + 7 prompts
    WritesEnv gate + approval tokensDefault OFF · HITL inbox · journal
    CostFree forever (MIT)Free v1 beta (fair-use caps)

  11. Security model for odoo-mcp plugins

    main

    Plugins in odoo-mcp run as arbitrary Python code within the server process using the server's Odoo credentials. There is no sandbox.

    Key Security Principles:

    • Opt-in Activation: Plugins are dormant by default. They only load if their entry-point name is explicitly listed in the ODOO_MCP_PLUGINS environment variable.
    • Fail-Isolation: If a plugin fails during load time, it is recorded in health_check.plugins.failed and skipped, allowing built-in tools to continue functioning.
    • The Plugin Contract: Plugins must adhere to the same constraints as built-in tools:
      • Use bounded reads.
      • Use api.redact_records on record data to respect field ACLs.
      • Return results using the {"success": ...} envelope.
      • No direct writes: Plugins must not mutate data directly; all writes must go through the gated write workflow. The API does not provide helpers to bypass this gate.

  12. Interact with multiple Odoo instances

    main

    If the server is configured with multiple named Odoo instances, every tool provided by odoo-mcp accepts an optional instance argument.

    Instead of using client-side headers, you simply instruct the agent to use a specific instance name. The agent will then pass instance="<name>" in its tool calls. You can use the list_instances tool to see which instances are currently available.