# Odoo MCP Server

[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-orange.svg)](https://modelcontextprotocol.io)

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
- **MCPServer** (MCP Python SDK 2.x, formerly 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>

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

</details>

<details>
<summary>Windows</summary>

```powershell
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

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

### 3. Install Dependencies

Using uv:

```bash
uv sync
```

### 4. Installing via MCP Settings

Add this configuration to your MCP settings:

**Using API Key (preferred):**

```json
{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["--directory", "/path/to/odoo-mcp-server", "run", "odoo-mcp-server"],
      "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:**

```json
{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["--directory", "/path/to/odoo-mcp-server", "run", "odoo-mcp-server"],
      "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`:

```json
{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["--directory", "/path/to/odoo-mcp-server", "run", "odoo-mcp-server"],
      "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`:

```json
{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["--directory", "/path/to/odoo-mcp-server", "run", "odoo-mcp-server"],
      "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):

```json
{
  "github.copilot.chat.mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["--directory", "/path/to/odoo-mcp-server", "run", "odoo-mcp-server"],
      "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`:

```json
{
  "context_servers": {
    "odoo": {
      "command": "uv",
      "args": ["--directory", "/path/to/odoo-mcp-server", "run", "odoo-mcp-server"],
      "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 the product catalog with optional language, `limits` and `offset` parameters
- Paginated: `limits` defaults to 50 (maximum 500); `offset` skips records. The result includes `total_count`, `returned` and `offset`
- Supports: English (en), Arabic (ar), French (fr), Spanish (es)
- Always returns a dictionary; when there are no products: `{"products": [], "message": "No products available."}`

**`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, quantity (default 1, must be > 0), create_invoice, finish_payment
- Customer must match exactly one customer by name (case-insensitive). If several or only partial matches exist, nothing is created and `candidates` (id, name) are returned
- `create_invoice` creates and posts the invoice via Odoo's standard invoicing wizard (invoices delivered quantities, following each product's invoicing policy)
- `finish_payment` registers a full payment and implies `create_invoice` (enabled automatically)
- If a step fails after the order exists, the result has `success: false`, the failed `step` and the `order_id`/`invoice_id` created so far. Do not retry blindly
- Not idempotent: it confirms orders, posts invoices and registers payments
- Not registered when `ODOO_READ_ONLY` is enabled

### Example Usage in MCP Client

```python
# 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,
    "quantity": 2,
    "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`  | IANA timezone for dates (validated at startup) | No               | `UTC`   | `Asia/Riyadh`           |
| `ODOO_TIMEOUT`   | XML-RPC socket timeout in seconds (> 0) | No | `30` | `60`                |
| `ODOO_PAYMENT_JOURNAL` | Journal name or code used by `create_order` payments (bank/cash journals only) | No | first bank/cash journal with an inbound payment method | `BNK1` |
| `ODOO_READ_ONLY` | `true`/`false`/`1`/`0`/`yes`/`no`; when true the write tools (`create_customer`, `create_order`) are not registered | No | `false` | `true` |
| `ODOO_LOG_LEVEL` | Logging level            | No               | `INFO`  | `DEBUG`                 |

### Validation Rules

- URL must start with `http://` or `https://`
- `ODOO_URL`, `ODOO_DATABASE` and one authentication method are required
- `ODOO_READ_ONLY` must be one of true/false/1/0/yes/no; `ODOO_TIMEOUT` must be a number > 0
- `ODOO_TIMEZONE` must be a valid IANA timezone name (e.g. `Asia/Riyadh`); an invalid value stops startup
- Connection timeout defaults to 30 seconds (`ODOO_TIMEOUT`)

## 🔧 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 / Least Privilege

- Create a **dedicated Odoo user** for this server (with an API key) and grant only the access rights it needs. A read-only role is enough for the read tools.
- Set `ODOO_READ_ONLY=true` unless you need to create customers or orders. The write tools are then not exposed to the MCP client at all.
- Write tools are annotated for MCP clients (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so they can ask for confirmation; `create_order` is marked destructive because it confirms orders, posts invoices and registers payments.
- Use `https://` for `ODOO_URL`. Over `http://` the credentials and data travel unencrypted; the server logs a warning at startup for `http://` URLs that are not localhost (it does not block them).

## 🔒 Security Considerations

- **Credentials**: Store sensitive information in environment variables
- **Validation**: All inputs are validated before processing; `limit`/`offset` are range-checked (limits above the maximum of 200, or 500 for products, are clamped), `search_by` and order `fields` must be known values
- **Error Handling**: Tool errors show only a short one-line summary of Odoo faults (tracebacks stripped) or the exception class name; full detail stays in the server log
- **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](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](https://modelcontextprotocol.io) - The underlying protocol specification
- [Odoo](https://www.odoo.com) - The ERP system this server integrates with
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - The MCP server framework used (2.x, `MCPServer`)

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