# 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.
