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

Navigate to the MCP server directory:

cd mcp-odoo-server

Install dependencies:

npm install

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

Log into your Odoo instance
Go to Settings → Users & Companies → Users
Open your user record
Go to the Preferences tab
Click New API Key button
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

Check Odoo is running: Ensure your Odoo server is accessible
Verify credentials: Make sure the API key is valid
Check firewall: Ensure port 8069 (or your custom port) is accessible
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.