Odoo MCP Server

The Odoo MCP Server is a robust and efficient implementation of the Model Context Protocol (MCP) designed to interact seamlessly with Odoo ERP systems. This server provides tools and resources to facilitate integration, automation, and enhanced functionality for Odoo-based workflows.

🚀 Features

• Product Management: Retrieve product catalogs, search products, and get detailed product information
• Customer Management: List, search, and create customers/partners with full contact details
• Order Processing: Create sales orders with multi-step workflows and retrieve order details
• Invoice Generation: Automatically create and post invoices from sales orders
• Payment Processing: Handle payment registration and processing workflows
• Multi-language Support: Support for English, Arabic, French, and Spanish product names
• Configurable Timezone: Set your preferred timezone via environment variable
• Structured Logging: Configurable log levels for debugging and monitoring
• Secure Authentication: XML-RPC based authentication with Odoo instances

🏗️ Architecture

The project follows a modular architecture with clear separation of concerns:

odoo-mcp-server/
├── src/mcpserver/
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # Application entry point
│   ├── config.py            # Configuration management and validation
│   ├── deployment.py        # MCP server deployment setup
│   ├── odoo_mcp_server.py   # Core server implementation
│   └── tools.py             # MCP tools and Odoo operations
├── pyproject.toml          # Project configuration and dependencies
├── .python-version         # Python version specification
└── README.md               # Project documentation

Core Components

• OdooMCPServer: Main server class handling Odoo connections and tool registration
• OdooConfig: Configuration management with environment variable validation
• OdooTools: Collection of MCP tools for Odoo operations
• FastMCP: MCP server framework integration

📋 Prerequisites

• Python 3.12 or higher
• Access to an Odoo instance (v17+ recommended)
• Valid Odoo user credentials with appropriate permissions

🛠️ Installation

1. Install UV

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:

<details> <summary>macOS/Linux</summary>

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

</details>

<details> <summary>Windows</summary>

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

</details>

After installation, restart your terminal to ensure UV is in your PATH.

2. Clone the Repository

git clone git@github.com:sameeroz/odoo-mcp-server.git
cd odoo-mcp-server

3. Install Dependencies

Using uv:

uv sync

4. Installing via MCP Settings

Add this configuration to your MCP settings:

Using API Key (preferred):

{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["run", "src/mcpserver/__main__.py"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_DATABASE": "your-database-name-here",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_USERNAME": "your-username-here"
      }
    }
  }
}

Using Username/Password:

{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["run", "src/mcpserver/__main__.py"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_DATABASE": "your-database-name-here",
        "ODOO_USERNAME": "your-username-here",
        "ODOO_PASSWORD": "your-password-here"
      }
    }
  }
}

<details> <summary>Claude Desktop</summary>

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["run", "src/mcpserver/__main__.py"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_USERNAME": "your-username-here",
        "ODOO_PASSWORD": "your-password-here",
        "ODOO_DATABASE": "your-database-name-here"
      }
    }
  }
}

</details>

<details> <summary>Cursor</summary>

Add to ~/.cursor/mcp_settings.json:

{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["run", "src/mcpserver/__main__.py"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_USERNAME": "your-username-here",
        "ODOO_PASSWORD": "your-password-here",
        "ODOO_DATABASE": "your-database-name-here"
      }
    }
  }
}

</details>

<details> <summary>VS Code (with GitHub Copilot)</summary>

Add to your VS Code settings (~/.vscode/mcp_settings.json or workspace settings):

{
  "github.copilot.chat.mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["run", "src/mcpserver/__main__.py"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_USERNAME": "your-username-here",
        "ODOO_PASSWORD": "your-password-here",
        "ODOO_DATABASE": "your-database-name-here"
      }
    }
  }
}

</details>

<details> <summary>Zed</summary>

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "odoo": {
      "command": "uv",
      "args": ["run", "src/mcpserver/__main__.py"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_USERNAME": "your-username-here",
        "ODOO_PASSWORD": "your-password-here",
        "ODOO_DATABASE": "your-database-name-here"
      }
    }
  }
}

</details>

🚀 Usage

Available MCP Tools

1. Product Operations

get_products

• Retrieve product catalog with optional language and limit parameters
• Supports: English (en), Arabic (ar), French (fr), Spanish (es)

get_product_details

• Get detailed information for a specific product by name
• Returns: name, price, description

2. Customer Management

get_customers

• Retrieve a paginated list of customers/partners
• Parameters: limit, offset
• Returns: customer list with contact details and total count

search_customers

• Search for customers by name, email, phone, or all fields
• Parameters: query, search_by ('name'|'email'|'phone'|'all'), limit

create_customer

• Create a new customer/partner with full contact details
• Parameters: name, email, phone, mobile, street, city, country, is_company
• Includes duplicate detection

3. Order Management

get_order_details

• Retrieve sales order information with customizable fields
• Supports filtering by order IDs and field selection

create_order

• Create new sales orders with automatic invoice and payment processing
• Parameters: customer_name, product_id, create_invoice, finish_payment

Example Usage in MCP Client

# Get products in Arabic
products = await mcp_client.call_tool("get_products", {
    "product_names_lang": "ar",
    "limits": 10
})

# Search for customers
customers = await mcp_client.call_tool("search_customers", {
    "query": "John",
    "search_by": "all",
    "limit": 5
})

# Create a customer
result = await mcp_client.call_tool("create_customer", {
    "name": "Acme Corp",
    "email": "contact@acme.com",
    "phone": "+1234567890",
    "country": "United States",
    "is_company": True
})

# Create an order with invoice and payment
result = await mcp_client.call_tool("create_order", {
    "customer_name": "John Doe",
    "product_id": 123,
    "create_invoice": True,
    "finish_payment": True
})

⚙️ Configuration

Environment Variables

Variable	Description	Required	Default	Example
ODOO_URL	Odoo instance URL	Yes		https://demo.odoo.com
ODOO_DATABASE	Database name	Yes		demo_db
ODOO_API_KEY	Odoo API key (preferred)	If no password		odoo_api_key_abc123
ODOO_USERNAME	Odoo username	Yes (for API key & password)		admin
ODOO_PASSWORD	Odoo password	If no API key		admin123
ODOO_TIMEZONE	Timezone for dates	No	UTC	Asia/Riyadh
ODOO_LOG_LEVEL	Logging level	No	INFO	DEBUG

Validation Rules

• URL must start with http:// or https://
• All environment variables are required
• Connection timeout: 30 seconds

🔧 Development

Key Classes

• OdooMCPServer: Main server orchestrator
• OdooConfig: Configuration management with validation
• OdooTools: MCP tool implementations
• ConfigValidationError: Custom exception for configuration errors

Adding New Tools

To add new MCP tools:

1. Add the tool method to the OdooTools class in tools.py
2. Use the @self.mcp.tool() decorator
3. Include proper type hints and docstrings

🔒 Security Considerations

• Credentials: Store sensitive information in environment variables
• Validation: All inputs are validated before processing
• Error Handling: Sensitive information is not exposed in error messages
• Timeouts: Connection timeouts prevent hanging requests
• Permissions: Ensure Odoo user has minimal required permissions

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guidelines
• Add type hints to all functions
• Include comprehensive docstrings
• Write tests for new functionality
• Update documentation as needed

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: Report bugs and feature requests via GitHub Issues
• Community: Join discussions in the project's GitHub Discussions

🔗 Related Projects

• Model Context Protocol - The underlying protocol specification
• Odoo - The ERP system this server integrates with
• FastMCP - The MCP server framework used

📊 Changelog

v0.2.0 (Current)

• Added customer/partner management tools (get, search, create)
• Added configurable timezone via ODOO_TIMEZONE env var
• Added configurable logging via ODOO_LOG_LEVEL env var
• Replaced print() with structured Python logging
• Fixed order creation flow (order lines now created before confirmation)
• Fixed product ID validation (uses = instead of ilike)
• Fixed exception handling in connection module
• Fixed domain format in order search
• Added proper type annotations to all tool parameters
• Added python-dotenv to dependencies

v0.1.0

• Initial release
• Basic product and order management tools
• Invoice and payment processing
• Multi-language support

---

Made with ❤️ by Sameeroz for the MCP and Odoo communities