odoo-mcp-beta 0.1.2

MCP Server for Odoo Integration

Odoo MCP Server

An MCP server implementation that integrates with Odoo ERP systems, enabling AI assistants like Claude to interact with Odoo data and functionality through the Model Context Protocol.

🎯 Quick Start

# Install the package
pip install odoo-mcp-beta

# Configure your Odoo connection
export ODOO_URL="https://your-odoo.com"
export ODOO_DB="your-database"
export ODOO_USERNAME="your-username"
export ODOO_PASSWORD="your-password"

# Run the server
python -m odoo_mcp

Features

• Comprehensive Odoo Integration: Full access to Odoo models, records, and methods
• XML-RPC Communication: Secure connection to Odoo instances via XML-RPC
• Flexible Configuration: Support for config files and environment variables
• Resource Pattern System: URI-based access to Odoo data structures
• Error Handling: Standardized error codes and messages following MCP specification
• Resource Subscriptions: Support for subscribing to resource changes and notifications
• MCP Specification Compliant: Fully compatible with the latest MCP specification (1.6.0+)
• Progress Reporting: Real-time progress updates during tool execution
• Batch Operations: Execute multiple operations efficiently in batch
• Advanced Search: Complex filtering with AND/OR logic, aggregations, and fuzzy search
• Metadata Exploration: Discover model schemas, constraints, and relationships
• Data Export/Import: Export data in JSON/CSV/XML formats, import with validation
• Security Management: User access control, field-level permissions, sudo operations
• Workflow Management: State transitions, workflow actions, and history tracking
• Shell Execution: Execute Python code in Odoo environment with full ORM access
• SQL Execution: Direct SQL query execution with safety features and result formatting

Tools

Core Operations

• execute_method - Execute any Odoo model method with full flexibility
• list_models - List available models with statistics and record counts

Batch Operations

• batch_execute - Execute multiple operations in a single transaction
• batch_create - Create multiple records efficiently
• batch_update - Update multiple records with different values
• batch_delete - Delete multiple records safely
• batch_copy - Duplicate records with optional default values

Advanced Search

• advanced_search - Complex filtering with AND/OR logic
• search_with_aggregation - GROUP BY queries with aggregations
• search_distinct - Get unique values for a field
• fuzzy_search - Fuzzy text search across multiple fields

Metadata & Schema

• get_field_metadata - Detailed field information and validation rules
• get_model_constraints - SQL and Python constraints
• get_model_relations - Many2one, One2many, Many2many relationships
• get_model_methods - Available methods for a model
• get_model_views - Form, tree, kanban view definitions

Data Import/Export

• export_data - Export in JSON, CSV, or XML formats
• import_data - Import with validation and update options
• export_template - Generate import templates with sample data

Security & Access Control

• get_user_info - Current user information and settings
• get_model_access_rights - CRUD permissions for models
• check_field_access - Field-level permission checks
• get_user_groups - User group memberships
• sudo_execute - Execute with elevated privileges

Workflow Management

• get_record_state - Current workflow state of records
• execute_workflow_action - Trigger workflow transitions
• get_available_actions - Available actions based on state
• bulk_state_transition - Bulk workflow operations
• get_workflow_history - Audit trail of state changes

HR & Employee Tools

• search_employee - Search employees by name
• get_employee_details - Comprehensive employee information
• get_employee_driver_info - Driver and vehicle details
• get_employee_banking_info - Banking information
• get_employee_payslips - Payroll records
• get_employee_contracts - Employment contracts
• get_employee_attendance - Attendance records
• get_employee_leaves - Leave requests and allocations
• get_employee_appraisals - Performance appraisals
• search_holidays - Search holidays by date range

Code Execution & Database Access

• execute_shell - Execute Python code in Odoo environment with ORM access
• execute_shell_multi - Execute multiple Python scripts in sequence
• execute_shell_code - Alias for execute_shell with additional options
• execute_sql - Execute SQL queries directly on Odoo database
• execute_sql_script - Execute multi-statement SQL scripts
• get_table_info - Get database table structure and constraints
• analyze_query - Analyze SQL query execution plans

All tools follow the MCP specification for error handling with standardized error codes and messages.

Resources

• odoo://models

  • Lists all available models in the Odoo system
  • Returns: Resource with MIME type application/json containing model information

• odoo://model/{model_name}

  • Get information about a specific model including fields
  • Example: odoo://model/res.partner
  • Returns: Resource with MIME type application/json containing model metadata and field definitions

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

  • Get a specific record by ID
  • Example: odoo://record/res.partner/1
  • Returns: Resource with MIME type application/json containing record data

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

  • Search for records that match a domain
  • Example: odoo://search/res.partner/[["is_company","=",true]]
  • Returns: Resource with MIME type application/json containing matching records (limited to 10 by default)

Resource Subscriptions

This server implements MCP resource subscriptions, allowing clients to be notified when resources change:

• resources/subscribe

  • Subscribe to changes in a specific resource
  • Parameters: uri - the resource URI to subscribe to
  • Returns: Confirmation of subscription success

• resources/unsubscribe

  • Unsubscribe from changes in a specific resource
  • Parameters: uri - the resource URI to unsubscribe from
  • Returns: Confirmation of unsubscription success

Configuration

Odoo Connection Setup

1. Create a configuration file named odoo_config.json:

{
  "url": "https://your-odoo-instance.com",
  "db": "your-database-name",
  "username": "your-username",
  "password": "your-password-or-api-key",
  "mcp_prefix": "my_odoo_production"
}

2. Alternatively, use environment variables:
   • ODOO_URL: Your Odoo server URL
   • ODOO_DB: Database name
   • ODOO_USERNAME: Login username
   • ODOO_PASSWORD: Password or API key
   • ODOO_MCP_PREFIX: Custom prefix for MCP commands and resources (default: database name)
   • ODOO_TIMEOUT: Connection timeout in seconds (default: 30)
   • ODOO_VERIFY_SSL: Whether to verify SSL certificates (default: true)
   • HTTP_PROXY: Force the ODOO connection to use an HTTP proxy

Multi-Database Support

When running multiple Odoo MCP servers connected to different databases, you can use the ODOO_MCP_PREFIX parameter to create unique command names for each server, avoiding conflicts in AI environments:

# For production Odoo server
export ODOO_MCP_PREFIX="aspire_production"
# Commands will appear as: aspire_production_execute_method

# For development Odoo server
export ODOO_MCP_PREFIX="aspire_dev"
# Commands will appear as: aspire_dev_execute_method

Without this setting, the database name will be used as a prefix by default. The MCP prefix ensures tools and resources have distinct names when using multiple Odoo instances with a single LLM.

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",
        "ODOO_MCP_PREFIX": "my_odoo"
      }
    }
  }
}

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",
        "ODOO_MCP_PREFIX": "my_odoo"
      }
    }
  }
}

Installation

Python Package

# Install the beta version with all new features
pip install odoo-mcp-beta

# Or install the stable version
pip install odoo-mcp

Running the Server

# Using the installed package
odoo-mcp  # or python -m 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

Development

Building from Source

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

Running Tests

pytest tests/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This MCP server is licensed under the MIT License.

Support

For issues, questions, or contributions, please visit our GitHub repository.