# MCP Odoo Server

A Model Context Protocol (MCP) server for connecting to Odoo databases via XML-RPC and JSON-RPC. This server enables AI assistants and other MCP clients to interact with Odoo databases, performing CRUD operations, managing modules, and executing administrative tasks.

## Features

- **Database Connection**: Connect to any Odoo instance using host, database name, username, and API key
- **CRUD Operations**: Create, Read, Update, and Delete records in any Odoo model
- **Search & Query**: Powerful search capabilities with domain filters
- **Module Management**: Install, uninstall, and upgrade Odoo modules
- **Field Inspection**: Get detailed field definitions and metadata
- **Access Control**: Check user permissions for operations
- **Version Info**: Get Odoo server version and capabilities

## Installation

1. Navigate to the MCP server directory:

```bash
cd mcp-odoo-server
```

2. Install dependencies:

```bash
npm install
```

3. Build the TypeScript code:

```bash
npm run build
```

## Configuration

### MCP Client Configuration

Add this server to your MCP client configuration (e.g., Claude Desktop):

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "odoo": {
      "command": "node",
      "args": [
        "/Users/malvernbright/development/Odoo/odoo-17.0+e.20251121/mcp-odoo-server/build/index.js"
      ]
    }
  }
}
```

### Odoo API Key

1. Log into your Odoo instance
2. Go to **Settings** → **Users & Companies** → **Users**
3. Open your user record
4. Go to the **Preferences** tab
5. Click **New API Key** button
6. Copy the generated API key (you'll use this as the password)

## Usage

### 1. Connect to Odoo Database

First, establish a connection to your Odoo database:

```typescript
// Parameters
{
  host: "localhost",           // or "example.odoo.com"
  database: "mydb",
  username: "admin@example.com",
  apiKey: "your-api-key-here",
  port: 8069,                  // optional, default: 8069
  protocol: "http"             // optional, default: "http", can be "https"
}
```

### 2. Search Records

Search for records matching specific criteria:

```typescript
// Find all customers named "John"
{
  model: "res.partner",
  domain: [["name", "ilike", "John"], ["customer_rank", ">", 0]],
  limit: 10,
  order: "name ASC"
}
```

### 3. Search and Read Records

Get full record data in one call:

```typescript
{
  model: "sale.order",
  domain: [["state", "=", "sale"]],
  fields: ["name", "partner_id", "amount_total", "date_order"],
  limit: 20
}
```

### 4. Read Specific Records

Read records by their IDs:

```typescript
{
  model: "res.partner",
  ids: [1, 2, 3],
  fields: ["name", "email", "phone"]
}
```

### 5. Create Records

Create a new record:

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

### 6. Update Records

Update existing records:

```typescript
{
  model: "res.partner",
  ids: [123],
  values: {
    phone: "+0987654321",
    street: "123 Main St"
  }
}
```

### 7. Delete Records

Delete records:

```typescript
{
  model: "res.partner",
  ids: [123, 456]
}
```

### 8. Get Field Definitions

Inspect model fields:

```typescript
{
  model: "sale.order",
  fields: ["state", "amount_total"],  // empty array for all fields
  attributes: ["string", "type", "required", "help"]
}
```

### 9. Module Management

Install a module:

```typescript
{
  module_name: "sale_management";
}
```

Uninstall a module:

```typescript
{
  module_name: "sale_management";
}
```

Upgrade a module:

```typescript
{
  module_name: "sale_management";
}
```

List installed modules:

```typescript
{
  limit: 50;
}
```

## Available Tools

| Tool                         | Description                              |
| ---------------------------- | ---------------------------------------- |
| `odoo_connect`               | Connect to an Odoo database              |
| `odoo_search`                | Search for record IDs matching criteria  |
| `odoo_search_read`           | Search and read records in one call      |
| `odoo_read`                  | Read specific records by ID              |
| `odoo_create`                | Create a new record                      |
| `odoo_write`                 | Update existing records                  |
| `odoo_delete`                | Delete records                           |
| `odoo_fields_get`            | Get field definitions for a model        |
| `odoo_execute`               | Execute any method on a model (advanced) |
| `odoo_version`               | Get Odoo server version info             |
| `odoo_check_access_rights`   | Check user permissions                   |
| `odoo_get_installed_modules` | List installed modules                   |
| `odoo_install_module`        | Install a module                         |
| `odoo_uninstall_module`      | Uninstall a module                       |
| `odoo_upgrade_module`        | Upgrade a module                         |

## Odoo Domain Syntax

Domains use Polish notation (prefix notation) and consist of tuples:

```python
# Simple conditions
[["field_name", "operator", "value"]]

# Multiple conditions (AND by default)
[["name", "ilike", "John"], ["age", ">", 18]]

# OR operator
["|", ["name", "=", "John"], ["name", "=", "Jane"]]

# NOT operator
["!", ["active", "=", False]]

# Complex example
["|", "&", ["name", "ilike", "John"], ["age", ">", 18], ["vip", "=", True]]
```

### Common Operators

- `=` - equals
- `!=` - not equals
- `>` - greater than
- `>=` - greater than or equal
- `<` - less than
- `<=` - less than or equal
- `like` - SQL LIKE
- `ilike` - case-insensitive LIKE
- `in` - in a list
- `not in` - not in a list
- `child_of` - child of (hierarchical)
- `parent_of` - parent of (hierarchical)

## Common Odoo Models

| Model              | Description                |
| ------------------ | -------------------------- |
| `res.partner`      | Contacts and Companies     |
| `res.users`        | Users                      |
| `sale.order`       | Sales Orders               |
| `purchase.order`   | Purchase Orders            |
| `account.move`     | Journal Entries (Invoices) |
| `stock.picking`    | Transfers/Deliveries       |
| `product.product`  | Products (variants)        |
| `product.template` | Product Templates          |
| `ir.module.module` | Installed Modules          |
| `res.company`      | Companies                  |
| `hr.employee`      | Employees                  |

## Development

### Watch Mode

For development with auto-rebuild:

```bash
npm run watch
```

### Run in Development

```bash
npm run dev
```

## Troubleshooting

### Connection Issues

1. **Check Odoo is running**: Ensure your Odoo server is accessible
2. **Verify credentials**: Make sure the API key is valid
3. **Check firewall**: Ensure port 8069 (or your custom port) is accessible
4. **Protocol**: Use `http` for local development, `https` for production

### Authentication Errors

- Verify your API key is correct
- Ensure the user has sufficient permissions
- Check that the database name is correct

### Module Installation Issues

- Only users with admin rights can install modules
- Some modules have dependencies that must be installed first
- Check the Odoo logs for detailed error messages

## Integration with odoo.conf

While this MCP server uses XML-RPC for remote connections, your local `odoo.conf` file is used to configure the Odoo server itself. Here's how they work together:

### odoo.conf (for Odoo Server)

```ini
[options]
db_host = localhost
db_port = 5432
db_user = odoo
db_password = your_postgres_password
db_name = False
```

### MCP Server (for Remote Access)

The MCP server connects to a running Odoo instance (which may be local or remote) using the XML-RPC API, similar to how the Odoo web interface or mobile apps connect.

## Security Notes

- **API Keys**: Never commit API keys to version control
- **Access Control**: The MCP server respects Odoo's security rules and access rights
- **HTTPS**: Always use HTTPS in production environments
- **Permissions**: Operations are limited by the authenticated user's permissions

## License

MIT

## Contributing

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