MCP Server for Odoo

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 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
• ⚡ Batch operations - create/read/update multiple records in a single API call
• 🗑️ Delete records respecting model-level permissions
• 📊 Browse multiple records and get formatted summaries
• 🔢 Count records matching specific criteria
• 📋 Inspect model fields to understand data structure
• 🔐 Secure access with API key or username/password authentication
• 🎯 Smart pagination for large datasets
• 💬 LLM-optimized output with hierarchical text formatting
• 🚀 YOLO Mode for quick access with any Odoo instance (no module required)
• 🌐 Locale Support: with the variable ODOO_LOCALE you can set the language (es_AR).

Like it ?

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!

Installation

Prerequisites

• Python 3.10 or higher
• Access to an Odoo instance (version 17.0+)
• For production use: The Odoo MCP module installed on your Odoo server
• For testing/demos: Any standard Odoo instance (use YOLO mode)

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-ei"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here"
      }
    }
  }
}

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

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

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

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

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

Alternative Installation Methods

# Install globally
pip install mcp-server-odoo-ei

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

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

Configuration

Environment Variables

The server requires the following environment variables:

*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
• When ODOO_LOCALE is set, Odoo will return translated field labels, selection values, and messages in that language

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

2. streamable-http

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

# Run with HTTP transport
uvx mcp-server-odoo-ei --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-ei

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.

Transport Configuration

{
  "mcpServers": {
    "odoo-remote": {
      "command": "uvx",
      "args": ["mcp-server-odoo-ei", "--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

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

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

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

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

{
  "mcpServers": {
    "odoo-test": {
      "command": "uvx",
      "args": ["mcp-server-odoo-ei"],
      "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"

Multi-Language Support

When you configure ODOO_LOCALE, Odoo will return all data in that language:

With ODOO_LOCALE=es_ES (Spanish):

# Field labels will be in Spanish
Cliente: Acme Corporation
Correo electrónico: info@acme.com
Estado: Borrador

# Selection values will be in Spanish
Tipo: Cliente
País: España

With ODOO_LOCALE=es_AR (Argentine Spanish):

# Uses Argentine terminology and formats
Razón Social: La Valeria S.A.
CUIT: 30-12345678-9
Provincia: Buenos Aires

Supported locales include:

• es_ES - Spanish (Spain)
• es_AR - Spanish (Argentina)
• es_MX - Spanish (Mexico)
• en_US - English (United States)
• en_GB - English (United Kingdom)
• fr_FR - French (France)
• pt_BR - Portuguese (Brazil)
• de_DE - German (Germany)
• Any other locale installed in your Odoo instance

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
• 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
• Use ["__all__"]: Returns all fields without metadata

read_records

Read multiple records by their IDs in a single API call (batch operation).

{
  "model": "res.partner",
  "record_ids": [1, 2, 3, 4, 5],
  "fields": ["name", "email", "phone"]
}

This is more efficient than calling get_record multiple times when you need to retrieve specific records by ID. Returns found records and reports any missing IDs.

list_models

List all models enabled for MCP access.

{}

create_record

Create a new record in Odoo.

{
  "model": "res.partner",
  "values": {
    "name": "New Customer",
    "email": "customer@example.com",
    "is_company": true
  }
}

update_record

Update an existing record.

{
  "model": "res.partner",
  "record_id": 42,
  "values": {
    "phone": "+1234567890",
    "website": "https://example.com"
  }
}

update_records

Update multiple records with the same values in a single API call (batch operation).

{
  "model": "project.task",
  "record_ids": [1, 2, 3, 4, 5],
  "values": {
    "display_in_project": true
  }
}

This is much more efficient than calling update_record multiple times when you need to apply the same changes to many records.

delete_record

Delete a record from Odoo.

{
  "model": "res.partner",
  "record_id": 42
}

Resources

The server also provides direct access to Odoo data through resource URIs:

• odoo://res.partner/record/1 - Get partner with ID 1
• odoo://product.product/search?domain=[["qty_available",">",0]] - Search products in stock
• odoo://sale.order/browse?ids=1,2,3 - Browse multiple sales orders
• odoo://res.partner/count?domain=[["customer_rank",">",0]] - Count customers
• odoo://product.product/fields - List available fields for products

Security

• Always use HTTPS in production environments
• Keep your API keys secure and rotate them regularly
• Configure model access carefully - only enable necessary models
• The MCP module respects Odoo's built-in access rights and record rules
• Each API key is linked to a specific user with their permissions

Troubleshooting

which uvx
# Example output: /Users/yourname/.local/bin/uvx

{
  "command": "/Users/yourname/.local/bin/uvx",
  "args": ["mcp-server-odoo-ei"]
}

{
  "env": {
    "ODOO_URL": "https://your-odoo.com",
    "ODOO_API_KEY": "your-key",
    "ODOO_DB": "your-database-name"
  }
}

{
  "env": {
    "ODOO_URL": "https://your-odoo.com",
    "ODOO_API_KEY": "your-key",
    "SSL_CERT_FILE": "/etc/ssl/cert.pem"
  }
}

{
  "env": {
    "ODOO_URL": "https://your-odoo.com",
    "ODOO_API_KEY": "your-key",
    "ODOO_MCP_LOG_LEVEL": "DEBUG"
  }
}

Performance Optimization

The server includes several performance optimizations:

Cache Configuration

Field metadata and permissions are cached on-demand. Records always fetch fresh data from Odoo.

Example configuration:

{
  "env": {
    "ODOO_URL": "https://your-odoo.com",
    "ODOO_API_KEY": "your-key",
    "ODOO_CACHE_FIELD_TTL": "7200",
    "ODOO_CACHE_PERMISSION_TTL": "600"
  }
}

Building Optimized Executables

For improved startup time and runtime performance, you can compile the server using Nuitka:

# Install build dependencies
pip install -e ".[build]"

# Build optimized executable
python scripts/build_nuitka.py

# Or build as standalone directory
python scripts/build_nuitka.py --standalone

The compiled executable provides:

• 20-50% faster runtime compared to interpreted Python
• Faster startup time with optimized imports
• Single file distribution (with --onefile)
• No Python runtime required on target machines

Development

# Clone the repository
git clone https://github.com/elevateinformatics/mcp-server-odoo.git
cd mcp-server-odoo

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest --cov

# Run the server
python -m mcp_server_odoo

# Using uvx
npx @modelcontextprotocol/inspector uvx mcp-server-odoo-ei

# Using local installation
npx @modelcontextprotocol/inspector python -m mcp_server_odoo

Testing

Transport Tests

You can test both stdio and streamable-http transports to ensure they're working correctly:

# Run comprehensive transport tests
python tests/run_transport_tests.py

This will test:

• stdio transport: Basic initialization and communication
• streamable-http transport: HTTP endpoint, session management, and tool calls

Unit Tests

For complete testing including unit and integration tests:

# Run all tests
uv run pytest --cov

# Run specific test categories
uv run pytest tests/test_tools.py -v
uv run pytest tests/test_server_foundation.py -v

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0) - see the LICENSE file for details.

Contributing

Contributions are very welcome! Please see the CONTRIBUTING guide for details.

And do not forget to give the project a star if you like it! :star: