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:

cd mcp-odoo-server

2. Install dependencies:

npm install

3. Build the TypeScript code:

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

{
  "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:

// 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:

// 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:

{
  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:

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

5. Create Records

Create a new record:

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

6. Update Records

Update existing records:

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

7. Delete Records

Delete records:

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

8. Get Field Definitions

Inspect model fields:

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

9. Module Management

Install a module:

{
  module_name: "sale_management";
}

Uninstall a module:

{
  module_name: "sale_management";
}

Upgrade a module:

{
  module_name: "sale_management";
}

List installed modules:

{
  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:

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

npm run watch

Run in Development

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)

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