Model Access

1. Go to Settings > MCP Server > Enabled Models
2. Add models you want to expose (e.g., res.partner, product.product)
3. Configure permissions for each model: - Read access - Write access - Create access - Delete access

API Key Setup

1. Navigate to Settings > Users & Companies > Users
2. Select the user for MCP access
3. Go to API Keys tab
4. Generate a new API key with appropriate scope
5. Use this key in your MCP client configuration

Client Setup

After installing the module and generating an API key, you can configure your AI assistant using either transport method:

Transport Options

The MCP server supports two transport types:

• stdio transport (default): For local AI assistants like Claude Desktop, VS Code extensions
• streamable-http transport: For web-based clients or remote connections

Standard Configuration (stdio transport):

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here"
      }
    }
  }
}

HTTP Transport Configuration:

For web-based or remote MCP clients:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo", "~~~~~~~~~~~~~reamable-http", "~~~~~~~~~~~~~
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here"
      }
    }
  }
}

Then connect your client to http://localhost:8000/mcp/

Client-Specific Examples

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json using the configuration examples above.

Cursor

Add to ~/.cursor/mcp_settings.json using the configuration examples above.

Claude Code

Run the following command to add the Odoo MCP server:

claude mcp add odoo \
  -e ODOO_URL=https://your-odoo-instance.com \
  -e ODOO_API_KEY=your-api-key-here \
  ~~~~~~~~~~~~~-server-odoo

Environment Variables

The MCP client requires one of the following authentication methods:

API Key Authentication (Recommended):

• ODOO_URL: Your Odoo instance URL (e.g., https://mycompany.odoo.com)
• ODOO_API_KEY: The API key generated in the previous step

Username/Password Authentication:

• ODOO_URL: Your Odoo instance URL (e.g., https://mycompany.odoo.com)
• ODOO_USER: Your Odoo username
• ODOO_PASSWORD: Your Odoo password

Optional Variables:

• ODOO_DB: Database name (auto-detected if not specified)

Security Groups

The module creates two security groups:

• MCP Administrator: Can configure MCP settings and manage enabled models
• MCP User: Can access MCP-enabled models based on configured permissions

Usage Examples

Once configured, you can query and manage your Odoo data using natural language:

Data Retrieval:

• "Show me all customers from Spain"
• "Find products with stock below 10 units"
• "List today's sales orders over $1000"
• "Search for unpaid invoices from last month"

Data Management:

• "Create a new customer contact for Acme Corporation"
• "Add a new product called 'Premium Widget' with price $99.99"
• "Update the phone number for customer John Doe"
• "Change the status of order SO/2024/001 to confirmed"
• "Delete the test contact we created earlier"

API Endpoints

The module provides several REST and XML-RPC endpoints:

REST API

• /mcp/health - Health check
• /mcp/system/info - System information
• /mcp/auth/validate - API key validation
• /mcp/models - List enabled models
• /mcp/models/{model}/access - Check model permissions

XML-RPC API

• /mcp/xmlrpc/common - Authentication
• /mcp/xmlrpc/db - Database operations
• /mcp/xmlrpc/object - Model operations

Security Considerations

• Use HTTPS in production environments
• Generate unique API keys for each integration
• Configure model access carefully - only enable necessary models
• Regularly review audit logs for suspicious activity
• Keep the module updated

Common Issues

Module Not Installing - Check that all dependencies are satisfied - Ensure Odoo 18.0 is being used

API Key Not Working - Verify the key is active in user settings - Check user has appropriate MCP permissions - Ensure correct API key scope

Model Access Denied - Confirm model is in enabled models list - Check operation permissions for the model - Verify user's security group membership

"spawn uvx ENOENT" Error

This error means UV is not installed on your local computer:

1. Install UV using the commands in the Installation section above

2. Restart your terminal and Claude Desktop

3. On macOS, if the issue persists, launch Claude from Terminal:

   open -a "Claude"
   

4. Alternative: Use the full path to uvx (find it with which uvx)

Database Access Denied

If you see "Access Denied" when the MCP server tries to list databases:

• This is normal security behavior on some Odoo instances
• You must specify the ODOO_DB environment variable in your configuration
• The server will use your specified database without validation