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:

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

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

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

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

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

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

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

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

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

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

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

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 |

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

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.

# Run with HTTP transport
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