Odoo MCP Server with HTTP Streamable Transport

A comprehensive MCP (Model Context Protocol) server for interacting with Odoo ERP systems, supporting both stdio and HTTP streamable transports for maximum flexibility and integration options.

🚀 Features

Core Functionality

• Dual Transport Support: Both stdio and HTTP streamable transports
• Comprehensive Odoo Integration: Full access to Odoo models, records, and methods
• Resource-based API: Browse models, records, and search results as MCP resources
• Tool-based API: Execute custom methods, search employees, and query holidays
• Real-time Streaming: Server-Sent Events (SSE) support for HTTP transport
• Session Management: Stateful and stateless HTTP session options

Transport Options

• Stdio Transport: Traditional stdin/stdout for direct MCP client integration
• HTTP Streamable Transport: RESTful HTTP API with optional SSE streaming
• Flexible Configuration: Stateful/stateless modes, JSON responses, CORS support

Developer Experience

• Hot Reload Development Server: Automatic restart on code changes
• Comprehensive Testing: Unit, integration, and end-to-end tests
• Health Monitoring: Built-in health checks and diagnostics
• Production Ready: Docker support, systemd services, Kubernetes deployment

Tools

• execute_method

  • Execute a custom method on an Odoo model
  • Inputs:
    • model (string): The model name (e.g., 'res.partner')
    • method (string): Method name to execute
    • args (optional array): Positional arguments
    • kwargs (optional object): Keyword arguments
  • Returns: Dictionary with the method result and success indicator

• search_employee

  • Search for employees by name
  • Inputs:
    • name (string): The name (or part of the name) to search for
    • limit (optional number): The maximum number of results to return (default 20)
  • Returns: Object containing success indicator, list of matching employee names and IDs, and any error message

• search_holidays

  • Searches for holidays within a specified date range
  • Inputs:
    • start_date (string): Start date in YYYY-MM-DD format
    • end_date (string): End date in YYYY-MM-DD format
    • employee_id (optional number): Optional employee ID to filter holidays
  • Returns: Object containing success indicator, list of holidays found, and any error message

Resources

• odoo://models

  • Lists all available models in the Odoo system
  • Returns: JSON array of model information

• odoo://model/{model_name}

  • Get information about a specific model including fields
  • Example: odoo://model/res.partner
  • Returns: JSON object with model metadata and field definitions

• odoo://record/{model_name}/{record_id}

  • Get a specific record by ID
  • Example: odoo://record/res.partner/1
  • Returns: JSON object with record data

• odoo://search/{model_name}/{domain}

  • Search for records that match a domain
  • Example: odoo://search/res.partner/[["is_company","=",true]]
  • Returns: JSON array of matching records (limited to 10 by default)

📋 Quick Start

Installation

git clone <repository-url>
cd mcp-odoo-http-streamable
pip install -e .

Configuration

Set your Odoo connection details:

export ODOO_URL="https://your-odoo-instance.com"
export ODOO_DB="your_database_name"
export ODOO_USERNAME="your_username" 
export ODOO_PASSWORD="your_password"

Running the Server

Stdio Transport (for MCP clients like Claude Desktop)

python run_server.py --transport stdio

HTTP Streamable Transport (for web applications)

# Basic HTTP server with sessions and SSE
python run_server.py --transport streamable-http --port 3000

# Stateless HTTP server (better for scaling)
python run_server.py --transport streamable-http --port 3000 --stateless

# JSON response mode (no SSE streams)
python run_server.py --transport streamable-http --port 3000 --json-response

📚 Documentation

• Transport Configuration - Detailed transport setup and options
• API Reference - Complete API documentation
• Deployment Guide - Production deployment instructions
• Development Guide - Contributing and extending the server

🛠️ Development

Setup Development Environment

# Quick setup with script
./scripts/setup_dev.sh

# Or manual setup
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Development Commands

# Start development server with hot reload
python scripts/dev_server.py --transport streamable-http

# Run tests with coverage
python scripts/test_runner.py --type unit --coverage

# Health check
python scripts/health_check.py

# Format and lint code
python scripts/test_runner.py --format --lint

Configuration Details

Environment Variables

# Required Odoo Configuration
export ODOO_URL="https://your-odoo-instance.com"
export ODOO_DB="your_database"
export ODOO_USERNAME="your_username"
export ODOO_PASSWORD="your_password"

# Optional Configuration
export ODOO_API_KEY="alternative_to_password"
export MCP_LOG_LEVEL="INFO"
export MCP_HOST="127.0.0.1"
export MCP_PORT="3000"

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "odoo": {
      "command": "python",
      "args": [
        "-m",
        "odoo_mcp"
      ],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_DB": "your-database-name",
        "ODOO_USERNAME": "your-username",
        "ODOO_PASSWORD": "your-password-or-api-key"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ODOO_URL",
        "-e",
        "ODOO_DB",
        "-e",
        "ODOO_USERNAME",
        "-e",
        "ODOO_PASSWORD",
        "mcp/odoo"
      ],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_DB": "your-database-name",
        "ODOO_USERNAME": "your-username",
        "ODOO_PASSWORD": "your-password-or-api-key"
      }
    }
  }
}

Installation

Python Package

pip install odoo-mcp

Running the Server

# Using the installed package
odoo-mcp

# Using the MCP development tools
mcp dev odoo_mcp/server.py

# With additional dependencies
mcp dev odoo_mcp/server.py --with pandas --with numpy

# Mount local code for development
mcp dev odoo_mcp/server.py --with-editable .

Build

Docker build:

docker build -t mcp/odoo:latest -f Dockerfile .

Parameter Formatting Guidelines

When using the MCP tools for Odoo, pay attention to these parameter formatting guidelines:

1. Domain Parameter:

   • The following domain formats are supported:
     • List format: [["field", "operator", value], ...]
     • Object format: {"conditions": [{"field": "...", "operator": "...", "value": "..."}]}
     • JSON string of either format
   • Examples:
     • List format: [["is_company", "=", true]]
     • Object format: {"conditions": [{"field": "date_order", "operator": ">=", "value": "2025-03-01"}]}
     • Multiple conditions: [["date_order", ">=", "2025-03-01"], ["date_order", "<=", "2025-03-31"]]

2. Fields Parameter:

   • Should be an array of field names: ["name", "email", "phone"]
   • The server will try to parse string inputs as JSON

License

This MCP server is licensed under the MIT License.