Mcp Server Odoo

MCP Server for Odoo

[](https://github.com/ivnvxd/mcp-server-odoo/actions/workflows/ci.yml) [](https://codecov.io/gh/ivnvxd/mcp-server-odoo) [](https://github.com/astral-sh/ruff) [](https://github.com/astral-sh/ty) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MPL-2.0)

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.

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.

Features

• 🔍 Search and retrieve any Odoo record (customers, products, invoices, etc.)
• ✨ Create new records with field validation and permission checks
• ✏️ Update existing data with smart field handling
• 🗑️ Delete records respecting model-level permissions
• 🔢 Count records matching specific criteria
• 📋 Inspect model fields to understand data structure
• 📊 Server-side aggregation — group, sum, and count without pulling raw rows
• ⚡ Workflow actions — invoke any public Odoo method (post invoice, confirm SO, etc.) via an opt-in escape hatch
• 🔐 Secure access with API key or username/password authentication
• 🎯 Smart pagination for large datasets
• 🧠 Smart field selection — automatically picks the most relevant fields per model
• 💬 LLM-optimized output with hierarchical text formatting
• 🌍 Multi-language support — get responses in your preferred language
• 🚀 YOLO Mode for quick access with any Odoo instance (no module required)

Installation

Prerequisites

• Python 3.10 or higher
• Access to an Odoo instance:
• Standard mode (production): Version 16.0+ with the Odoo MCP module 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:

macOS/Linux

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

Windows

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

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"
      }
    }
  }
}

Claude Desktop

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"
      }
    }
  }
}

Claude Code

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

Cursor

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"
      }
    }
  }
}

VS Code (with GitHub Copilot)

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".

Windsurf

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"
      }
    }
  }
}

Zed

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"
        }
      }
    }
  }
}

Alternative Installation Methods

Using Docker

Run with Docker — no Python installation required:

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ODOO_URL=http://host.docker.internal:8069",
        "-e", "ODOO_API_KEY=your-api-key-here",
        "ivnvxd/mcp-server-odoo"
      ]
    }
  }
}

> Note: Use host.docker.internal instead of localhost to connect to Odoo running on the host machine.

For HTTP transport:

docker run --rm -p 8000:8000 \
  -e ODOO_URL=http://host.docker.internal:8069 \
  -e ODOO_API_KEY=your-api-key-here \
  ivnvxd/mcp-server-odoo --transport streamable-http --host 0.0.0.0

> ⚠️ 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).

The image is also available on GHCR: ghcr.io/ivnvxd/mcp-server-odoo

Using pip

# Install globally
pip install mcp-server-odoo

# Or use pipx for isolated environment
pipx install mcp-server-odoo

Then use mcp-server-odoo as the command in your MCP configuration.

From source

git clone https://github.com/ivnvxd/mcp-server-odoo.git
cd mcp-server-odoo
pip install -e .

Then use the full path to the package in your MCP configuration.

Configuration

Environment Variables

The server requires the following environment variables:

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | ODOO_URL | Yes | Your Odoo instance URL | https://mycompany.odoo.com | | ODOO_API_KEY | Yes | API key for authentication | 0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd | | ODOO_USER | Yes | Username (if not using API key) | admin | | ODOO_PASSWORD | Yes* | Password (if not using API key) | admin | | ODOO_DB | No | Database name (auto-detected if not set) | mycompany | | ODOO_LOCALE | No | Language/locale for Odoo responses | es_ES, fr_FR, de_DE | | ODOO_YOLO | No | YOLO mode - bypasses MCP security (⚠️ DEV ONLY) | off, read, true | | ODOO_MCP_ENABLE_METHOD_CALLS | No | Enable the call_model_method tool — requires ODOO_YOLO=true (⚠️ Dangerous, see [call_model_method](#callmodelmethod)) | false, true |

*Either ODOO_API_KEY or both ODOO_USER and ODOO_PASSWORD are required.

Notes:

• If database listing is restricted on your server, you must specify ODOO_DB
• API key authentication is recommended for better security
• The server also loads environment variables from a .env file in the working directory

Advanced Configuration

| Variable | Default | Description | |----------|---------|-------------| | ODOO_MCP_DEFAULT_LIMIT | 10 | Default number of records returned per search | | ODOO_MCP_MAX_LIMIT | 100 | Maximum allowed record limit per request | | ODOO_MCP_MAX_SMART_FIELDS | 15 | Maximum fields returned by smart field selection | | ODOO_MCP_LOG_LEVEL | INFO | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | | ODOO_MCP_LOG_JSON | false | Enable structured JSON log output | | ODOO_MCP_LOG_FILE | — | Path for rotating log file (10 MB, 5 backups) | | ODOO_MCP_TRANSPORT | stdio | Transport type (stdio, streamable-http) | | ODOO_MCP_HOST | localhost | Host to bind for HTTP transport | | ODOO_MCP_PORT | 8000 | Port to bind for HTTP transport | | 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. Unset leaves the default (no host validation). | | 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. |

Transport Options

The server supports multiple transport protocols for different use cases:

1. stdio (Default)

Standard input/output transport - used by desktop AI applications like Claude Desktop.

# Default transport - no additional configuration needed
uvx mcp-server-odoo

2. streamable-http

Standard HTTP transport for REST API-style access and remote connectivity.

> ⚠️ 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.

# Run with HTTP transport (localhost only — safe default)
uvx mcp-server-odoo --transport streamable-http --port 8000

# Binding 0.0.0.0 exposes the server to the network — see the security note above
uvx mcp-server-odoo --transport streamable-http --host 0.0.0.0 --port 8000

# Or use environment variables
export ODOO_MCP_TRANSPORT=streamable-http
export ODOO_MCP_HOST=0.0.0.0
export ODOO_MCP_PORT=8000
uvx mcp-server-odoo

The HTTP endpoint will be available at: http://localhost:8000/mcp/

> 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. Requires MCP library v1.9.4 or higher for proper session management.

Running streamable-http transport for remote access

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

Setting up Odoo

1. Install the MCP module:

• Download the mcp_server module
• Install it in your Odoo instance
• Navigate to Settings > MCP Server

1. Enable models for MCP access:

• Go to Settings > MCP Server > Enabled Models
• Add models you want to access (e.g., res.partner, product.product)
• Configure permissions (read, write, create, delete) per model

1. Generate an API key:

• Go to Settings > Users & Companies > Users
• Select your user
• Under the "API Keys" tab, create a new key
• Copy the key for your MCP configuration

YOLO Mode (Development/Testing Only) ⚠️

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.

🚨 WARNING: Never use YOLO mode in production environments!

YOLO Mode Levels

1. Read-Only Mode (ODOO_YOLO=read):

• Allows all read operations (search, read, count)
• Blocks all write operations (create, update, delete)
• Safe for demos and testing
• Shows "READ-ONLY" indicators in responses

1. Full Access Mode (ODOO_YOLO=true):

• Allows ALL operations without restrictions
• Full CRUD access to all models
• EXTREMELY DANGEROUS - use only in isolated environments
• Shows "FULL ACCESS" warnings in responses

YOLO Mode Configuration

Read-Only YOLO Mode (safer for demos)

{
  "mcpServers": {
    "odoo-demo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "admin",
        "ODOO_DB": "demo",
        "ODOO_YOLO": "read"
      }
    }
  }
}

Full Access YOLO Mode (⚠️ use with extreme caution)

{
  "mcpServers": {
    "odoo-test": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "admin",
        "ODOO_DB": "test",
        "ODOO_YOLO": "true"
      }
    }
  }
}

When to Use YOLO Mode

✅ Appropriate Uses:

• Local development with test data
• Quick demos with non-sensitive data
• Testing MCP clients before installing the MCP module
• Prototyping in isolated environments

❌ Never Use For:

• Production environments
• Instances with real customer data
• Shared development servers
• Any environment with sensitive information

YOLO Mode Security Notes

• Connects directly to Odoo's standard XML-RPC endpoints
• Bypasses all MCP access controls and model restrictions
• No rate limiting is applied
• All operations are logged but not restricted
• Model listing shows 200+ models instead of just enabled ones

Usage Examples

Once configured, you can ask Claude:

Search & Retrieve:

• "Show me all customers from Spain"
• "Find products with stock below 10 units"
• "List today's sales orders over $1000"
• "Search for unpaid invoices from last month"
• "Count how many active employees we have"
• "Show me the contact information for Microsoft"

Create & Manage:

• "Create a new customer contact for Acme Corporation"
• "Add a new product called 'Premium Widget' with price $99.99"
• "Create a calendar event for tomorrow at 2 PM"
• "Update the phone number for customer John Doe to +1-555-0123"
• "Change the status of order SO/2024/001 to confirmed"
• "Delete the test contact we created earlier"

Available Tools

search_records

Search for records in any Odoo model with filters.

{
  "model": "res.partner",
  "domain": [["is_company", "=", true], ["country_id.code", "=", "ES"]],
  "fields": ["name", "email", "phone"],
  "limit": 10
}

Field Selection Options:

• Omit fields or set to null: Returns smart selection of common fields
• Specify field list: Returns only those specific fields
• An empty list [] is treated like null (smart defaults)
• Use ["__all__"]: Returns all fields (use with caution)

get_record

Retrieve a specific record by ID.

{
  "model": "res.partner",
  "record_id": 42,
  "fields": ["name", "email", "street", "city"]
}

Field Selection Options:

• Omit fields or set to null: Returns smart selection of common fields with metadata
• Specify field list: Returns only those specific fields
• An empty list [] is treated like null (smart defaults)
• Use ["__all__"]: Returns all fields without metadata

list_models

List all models enabled for MCP access.

`

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ivnvxd
• Source: ivnvxd/mcp-server-odoo
• License: MPL-2.0

Install and usage instructions live in the source repository linked above.