### Development Setup and Running

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

Clone the repository, install dependencies in development mode, and run tests or the server. Includes commands for cloning, installing, running tests with coverage, starting the server, and checking the version.

```bash
# Clone the repository
git clone https://github.com/ivnvxd/mcp-server-odoo.git
cd mcp-server-odoo

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest --cov

# Run the server
python -m mcp_server_odoo

# Check version
python -m mcp_server_odoo --version
```

--------------------------------

### Install mcp-server-odoo from source

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Install mcp-server-odoo by cloning the repository and using pip.

```bash
git clone https://github.com/ivnvxd/mcp-server-odoo.git
cd mcp-server-odoo
pip install -e .
```

--------------------------------

### Install mcp-server-odoo via uvx

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Use uvx for recommended installation of the mcp-server-odoo package.

```bash
uvx mcp-server-odoo
```

--------------------------------

### Install Project in Development Mode

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/CONTRIBUTING.md

Install the project in editable mode with development dependencies using uv.

```bash
uv pip install -e ".[dev]"
```

--------------------------------

### OdooConfig Initialization Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Demonstrates initializing OdooConfig with an API key and retrieving endpoint paths.

```python
config = OdooConfig(url="https://odoo.example.com", api_key="key")
paths = config.get_endpoint_paths()
# Returns: {
#     "db": "/xmlrpc/db",
#     "common": "/mcp/xmlrpc/common",
#     "object": "/mcp/xmlrpc/object"
# }
```

--------------------------------

### Install UV on Windows

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

Installs the UV package manager on Windows systems using a PowerShell command. A terminal restart is required after installation.

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Install via pip

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

Commands to install the mcp-server-odoo package globally or using pipx for an isolated environment.

```bash
# Install globally
pip install mcp-server-odoo

# Or use pipx for isolated environment
pipx install mcp-server-odoo
```

--------------------------------

### Minimal Configuration Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/configuration.md

Sets the ODOO_URL and ODOO_API_KEY for a minimal standard configuration.

```bash
export ODOO_URL=https://company.odoo.com
export ODOO_API_KEY=0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd
```

--------------------------------

### Configuration Example with Database

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/configuration.md

Includes ODOO_DB in addition to ODOO_URL and ODOO_API_KEY for a configuration that specifies a particular Odoo database.

```bash
export ODOO_URL=https://company.odoo.com
export ODOO_API_KEY=0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd
export ODOO_DB=company_production
```

--------------------------------

### .env File Configuration Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/configuration.md

Example of a .env file for configuring the MCP Server Odoo, including connection details, logging, limits, transport, and YOLO mode settings.

```bash
# Connection
ODOO_URL=https://mycompany.odoo.com
ODOO_API_KEY=0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd
ODOO_DB=mycompany

# Logging
ODOO_MCP_LOG_LEVEL=INFO
ODOO_MCP_LOG_FILE=/var/log/mcp-server-odoo/server.log

# Limits
ODOO_MCP_DEFAULT_LIMIT=10
ODOO_MCP_MAX_LIMIT=100

# Transport
ODOO_MCP_TRANSPORT=stdio

# YOLO Mode (development only)
# ODOO_YOLO=read
# ODOO_MCP_ENABLE_METHOD_CALLS=false
```

--------------------------------

### Install mcp-server-odoo via pip

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Install the mcp-server-odoo package using pip.

```bash
pip install mcp-server-odoo
```

--------------------------------

### OdooMCPServer StdIO Transport Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooMCPServer.md

Example of running the OdooMCPServer using the default stdio transport. This is commonly used by AI assistants like Claude Desktop.

```python
asyncio.run(server.run_stdio())
```

--------------------------------

### Install UV on macOS/Linux

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

Installs the UV package manager on macOS or Linux systems using a curl command. Ensure your terminal is restarted after installation.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Example Output for Field Definitions

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/resources.md

This is an example of the plain text output format for field definitions, including details like field name, type, label, and help text.

```text
Field Definitions for res.partner (45 total fields)

========================================
Field: id
Type: integer
String: ID
Required: No
Readonly: Yes
Help: Unique identifier

Field: name
Type: char
String: Name
Required: Yes
Readonly: No
Help: The name of the partner

Field: country_id
Type: many2one
String: Country
Required: No
Readonly: No
Relation: res.country
Help: Country of the partner

... (more fields)
```

--------------------------------

### Initialize and Run Odoo MCPServer

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/00-START-HERE.txt

Use this snippet to initialize the OdooMCPServer with a configuration and start it using standard input/output. Ensure you have imported OdooMCPServer and OdooConfig.

```python
from mcp_server_odoo import OdooMCPServer, OdooConfig
import asyncio

config = OdooConfig(
    url="https://odoo.example.com",
    api_key="key..."
)
server = OdooMCPServer(config)
asyncio.run(server.run_stdio())
```

--------------------------------

### Performance Logging

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Example of how to use the performance logger to track specific operations.

```python
from mcp_server_odoo.logging_config import perf_logger

perf_logger.track_operation("operation_name")
```

--------------------------------

### Get MCP Server Version

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/CONTRIBUTING.md

Command to retrieve the installed version of the MCP Server for Odoo.

```bash
python -m mcp_server_odoo --version
```

--------------------------------

### Example URL Generation

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

This is an example of a generated URL for direct access to a record in Odoo.

```text
https://company.odoo.com/web#id=42&model=res.partner&view_type=form
```

--------------------------------

### OdooMCPServer HTTP Transport Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooMCPServer.md

Example of running the OdooMCPServer using the streamable-http transport. This allows for REST-style access or remote connectivity. Note the security implications of exposing HTTP.

```python
asyncio.run(server.run_http(host="0.0.0.0", port=8000))
```

--------------------------------

### Example Odoo MCP Tool Request: Sale Order with Context

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/tools.md

An example request to the Odoo MCP tool for the 'sale.order' model, calling 'action_confirm' with keyword arguments including context.

```json
{
  "model": "sale.order",
  "method": "action_confirm",
  "arguments": [[7]],
  "keyword_arguments": {"context": {"lang": "en_US"}}
}
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```git
feat: add multi-language support via ODOO_LOCALE
fix: handle models without name field in create_record
refactor: rename test markers — integration→mcp, e2e→yolo
```

```git
fix: use password auth for MCP integration tests in CI

Remove fake ODOO_API_KEY from CI env vars — it caused Access Denied
errors because Odoo rejected the dummy key at the XML-RPC dispatch
level. Tests now use password-only auth which works with
use_api_keys=False.
```

--------------------------------

### Example Odoo MCP Tool Request: Account Move

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/tools.md

An example request to the Odoo MCP tool for the 'account.move' model, specifically calling the 'action_post' method.

```json
{
  "model": "account.move",
  "method": "action_post",
  "arguments": [[42]]
}
```

--------------------------------

### List Available Resources

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/resources.md

Use this GET request to list all available resources and their patterns. The response includes resource templates, enabled models, and usage guidance.

```http
GET /mcp/resources
```

--------------------------------

### Testing with MCP Inspector

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

Use the MCP Inspector tool to test the server, either with UVX or a local installation. This helps in verifying the server's functionality.

```bash
# Using uvx
npx @modelcontextprotocol/inspector uvx mcp-server-odoo

# Using local installation
npx @modelcontextprotocol/inspector python -m mcp_server_odoo
```

--------------------------------

### Docker Installation with Environment Variables

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

Docker configuration for running the Odoo server without Python installation. Uses environment variables for ODOO_URL and ODOO_API_KEY.

```json
{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ODOO_URL=http://host.docker.internal:8069",
        "-e", "ODOO_API_KEY=your-api-key-here",
        "ivnvxd/mcp-server-odoo"
      ]
    }
  }
}
```

--------------------------------

### Run MCP Server with stdio Transport

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Starts the MCP server using the standard input/output transport. This is the default and suitable for local clients and Claude Desktop.

```bash
python -m mcp_server_odoo --transport stdio
```

--------------------------------

### Example Error Response

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/resources.md

This is an example of a plain text error message returned by the MCP Server Odoo when a resource-related issue occurs, such as a model not being found or enabled.

```text
Error: Model 'nonexistent.model' not found or not enabled for MCP access.
```

--------------------------------

### ResourceTemplateInfo Model

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/types.md

Represents information about an available resource URI template. It includes the URI pattern, description, parameters, an example, and optional notes.

```python
class ResourceTemplateInfo(BaseModel):
    uri_template: str
    description: str
    parameters: Dict[str, str]
    example: str
    note: Optional[str] = None
```

--------------------------------

### Run MCP Server with streamable-http Transport

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Starts the MCP server using the streamable-http transport, enabling REST API-style access. Requires specifying host and port. Use with caution due to lack of built-in authentication.

```bash
python -m mcp_server_odoo --transport streamable-http --host localhost --port 8000
```

--------------------------------

### Get All Permissions

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/AccessController.md

Retrieves a dictionary of permissions for all models enabled for MCP access. Useful for a comprehensive overview of access rights.

```python
all_perms = controller.get_all_permissions()
for model, perms in all_perms.items():
    operations = []
    if perms.can_read:
        operations.append('read')
    if perms.can_write:
        operations.append('write')
    print(f"{model}: {', '.join(operations)}")
```

--------------------------------

### Create Record Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/tools.md

Use this snippet to create a new record in Odoo. Specify the model and the values for the fields you want to set.

```json
{
  "model": "res.partner",
  "values": {
    "name": "Acme Corporation",
    "email": "info@acme.com",
    "phone": "+1-555-0123",
    "country_id": 233
  }
}
```

--------------------------------

### Get Singleton Configuration Instance

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Retrieves the global OdooConfig instance. The configuration is loaded on the first call and cached for subsequent calls.

```python
config = get_config()
print(f"Connected to: {config.url}")
```

--------------------------------

### Run MCP Integration Tests

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/CONTRIBUTING.md

Execute MCP integration tests, which require Odoo and the MCP module to be installed.

```bash
uv run pytest -m "mcp" -v
```

--------------------------------

### Handle Configuration Errors

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/errors.md

Catch ValueError exceptions during Odoo configuration setup. This typically indicates invalid configuration parameters.

```python
try:
    config = OdooConfig(
        url="invalid-url",
        api_key="key"
    )
except ValueError as e:
    print(f"Config error: {e}")
```

--------------------------------

### Configure streamable-http transport using environment variables

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

This demonstrates how to configure the MCP Server Odoo to use the streamable-http transport, host, and port via environment variables. The server is then started with these configurations applied.

```bash
export ODOO_MCP_TRANSPORT=streamable-http
export ODOO_MCP_HOST=0.0.0.0
export ODOO_MCP_PORT=8000
uvx mcp-server-odoo
```

--------------------------------

### Aggregate Records Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/tools.md

Use this snippet to perform server-side aggregation on records. Specify the model, fields to group by, and optional aggregation functions and domain filters.

```json
{
  "model": "sale.order",
  "groupby": ["date_order:month", "state"],
  "aggregates": ["amount_total:sum", "__count"],
  "domain": [["state", "in", ["sale", "done"]]]
}
```

--------------------------------

### Run MCP Server Odoo with streamable-http transport

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

This command starts the MCP Server Odoo using the streamable-http transport, binding to localhost on port 8000. Ensure to review security implications before exposing the server beyond localhost.

```bash
uvx mcp-server-odoo --transport streamable-http --port 8000
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/CONTRIBUTING.md

Clone the repository and change into the project directory to begin development.

```bash
git clone https://github.com/<your-username>/mcp-server-odoo.git
cd mcp-server-odoo
```

--------------------------------

### Implement Retry Logic with Exponential Backoff

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/errors.md

Use a loop with a try-catch block to implement retry logic for transient errors like MCPConnectionError. This example includes exponential backoff to gradually increase the delay between retries.

```python
from mcp_server_odoo.error_handling import MCPConnectionError
import time

max_retries = 3
for attempt in range(max_retries):
    try:
        connection.reconnect()
        break
    except MCPConnectionError as e:
        if attempt < max_retries - 1:
            time.sleep(2 ** attempt)  # Exponential backoff
        else:
            raise
```

--------------------------------

### Aggregate Odoo Records by Month and Sum Amount

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

Perform server-side aggregation to get totals or groupings. This example groups sales orders by month and sums their total amount.

```json
{
  "model": "sale.order",
  "groupby": ["date_order:month"],
  "aggregates": ["amount_total:sum"],
  "domain": [["state", "in", ["sale", "done"]]]
}
```

--------------------------------

### Basic OdooMCPServer Usage

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Demonstrates how to create an OdooConfig, instantiate OdooMCPServer, and run it using asyncio for stdio transport.

```python
from mcp_server_odoo import OdooMCPServer, OdooConfig
import asyncio

# Create config
config = OdooConfig(
    url="https://mycompany.odoo.com",
    api_key="0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd"
)

# Create server
server = OdooMCPServer(config)

# Run server
asyncio.run(server.run_stdio())
```

--------------------------------

### Display Version Information

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/configuration.md

Use the --version flag to display the server version and exit.

```bash
mcp-server-odoo --version
# Output: odoo-mcp-server v0.7.1
```

--------------------------------

### OdooConfig Initialization with Credentials

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Initializes OdooConfig using username and password for authentication. Specify URL, credentials, and database.

```python
config = OdooConfig(
    url="https://company.odoo.com",
    username="admin",
    password="admin_password",
    database="company_db"
)
```

--------------------------------

### Display Help for CLI Arguments

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/configuration.md

Run the mcp-server-odoo command with --help to see all available command-line arguments, which override environment variables.

```bash
mcp-server-odoo --help
```

--------------------------------

### from_env() Class Method

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Creates an OdooConfig instance by loading settings from environment variables, optionally from a specified .env file.

```APIDOC
## `from_env(env_file: Optional[Path] = None) -> OdooConfig`

### Description
Create configuration from environment variables.

### Method
`from_env`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Description |
|-----------|------|-------------|
| `env_file` | `Optional[Path]` | Optional path to .env file |

### Returns
- `OdooConfig` instance with validated settings

### Raises
- `ValueError`: If required fields missing or invalid

### Request Example
```python
from mcp_server_odoo.config import OdooConfig

# Assuming environment variables like
# ODOO_URL=https://odoo.example.com
# ODOO_API_KEY=your_api_key

config = OdooConfig.from_env()
# Loads from environment variables and optionally a .env file
```

### Response
None (Class method returns an instance, does not have a separate response structure)

### Response Example
None
```

--------------------------------

### Load Configuration from .env File

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Loads configuration from environment variables and an optional .env file. If no path is provided, it auto-searches for a .env file.

```python
from pathlib import Path
config = load_config(Path(".env.production"))
```

--------------------------------

### Initialize OdooMCPServer

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooMCPServer.md

Initialize the Odoo MCP server instance with an explicit OdooConfig or by loading from environment variables.

```python
from mcp_server_odoo import OdooMCPServer, OdooConfig

# Initialize with explicit config
config = OdooConfig(
    url="https://mycompany.odoo.com",
    api_key="0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd"
)
server = OdooMCPServer(config)

# Or use environment variables
server = OdooMCPServer()
```

--------------------------------

### OdooConfig Initialization with API Key

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Initializes OdooConfig using an API key for authentication. Specify URL, API key, database, and log level.

```python
config = OdooConfig(
    url="https://company.odoo.com",
    api_key="0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd",
    database="company_db",
    log_level="INFO"
)
```

--------------------------------

### Get Endpoint Paths

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Retrieves Odoo XML-RPC endpoint paths, adapting to standard or YOLO mode.

```python
def get_endpoint_paths(self) -> Dict[str, str]:
    """Get appropriate XML-RPC endpoint paths based on mode."""
    pass
```

--------------------------------

### Configure UVX Command Path

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

If you encounter 'spawn uvx ENOENT' errors, you may need to specify the full path to the UVX executable. Find the path using 'which uvx' and update your configuration.

```json
{
  "command": "/Users/yourname/.local/bin/uvx",
  "args": ["mcp-server-odoo"]
}
```

--------------------------------

### Initialize OdooConnection

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConnection.md

Instantiate OdooConnection with configuration, timeout, and an optional performance manager. Ensure OdooConfig is properly set up with your Odoo instance URL and API key.

```python
from mcp_server_odoo import OdooConfig, OdooConnection

config = OdooConfig(
    url="https://mycompany.odoo.com",
    api_key="0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd"
)
connection = OdooConnection(config, timeout=30)
```

--------------------------------

### List Available Odoo Models

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/tools.md

Call this tool to get a list of all models available through MCP. This is useful for discovering which data can be accessed or manipulated.

```json
{}
```

--------------------------------

### Count All Records in a Model

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/resources.md

Use this resource to get the total count of records in a specified Odoo model. The model name is provided in the URI.

```uri
odoo://res.partner/count
```

```uri
odoo://sale.order/count
```

--------------------------------

### Get Odoo Model Field Definitions

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConnection.md

Retrieves the definitions and metadata for all fields of a given Odoo model. Useful for understanding available fields and their properties.

```python
fields = connection.fields_get('res.partner')
for field_name, metadata in fields.items():
    print(f"{field_name}: {metadata.get('type')}")
```

--------------------------------

### Create OdooConfig from Environment Variables

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Class method to instantiate OdooConfig by loading settings from environment variables, optionally from a .env file.

```python
@classmethod
def from_env(env_file: Optional[Path] = None) -> OdooConfig:
    """Create configuration from environment variables."""
    pass
```

```python
config = OdooConfig.from_env()
# Loads from environment variables and .env file
```

--------------------------------

### Catch Specific Exceptions

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Demonstrates how to catch specific exceptions like AuthenticationError and MCPPermissionError during connection attempts.

```python
from mcp_server_odoo.error_handling import AuthenticationError, MCPPermissionError

try:
    connection.connect()
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except MCPPermissionError as e:
    print(f"Permission denied: {e.message}")
```

--------------------------------

### Run All Tests

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/CONTRIBUTING.md

Execute all tests in the project, including code coverage.

```bash
uv run pytest --cov
```

--------------------------------

### Claude Code CLI Installation

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

Command-line interface command for Claude Code to add Odoo server configuration. Sets ODOO_URL, ODOO_API_KEY, ODOO_DB, and the command.

```bash
claude mcp add odoo \
  --env ODOO_URL=https://your-odoo-instance.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_DB=your-database-name \
  -- uvx mcp-server-odoo
```

--------------------------------

### Initialize AccessController with API Key Authentication

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/AccessController.md

Configures the AccessController to use API key authentication. The API key is sent in HTTP headers for permission validation.

```python
config = OdooConfig(
    url="https://odoo.example.com",
    api_key="0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd"
)
controller = AccessController(config, auth_method="api_key")
```

--------------------------------

### Environment Configuration for Odoo Server

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Shows how to set environment variables for Odoo URL, API key, and database to run the server with default settings.

```bash
export ODOO_URL=https://mycompany.odoo.com
export ODOO_API_KEY=0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd
export ODOO_DB=mycompany

# Run with defaults
python -m mcp_server_odoo
```

--------------------------------

### OdooMCPServer Initialization

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooMCPServer.md

Initializes the Odoo MCP server. It can be configured explicitly with an OdooConfig object or by loading settings from environment variables.

```APIDOC
## `__init__(config: Optional[OdooConfig] = None)`

### Description
Initialize the Odoo MCP server instance.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `config` | `Optional[OdooConfig]` | `None` | Optional OdooConfig instance. If not provided, will load from environment variables. |

### Raises
- `ValueError`: If configuration is invalid or missing required fields

### Example
```python
from mcp_server_odoo import OdooMCPServer, OdooConfig

# Initialize with explicit config
config = OdooConfig(
    url="https://mycompany.odoo.com",
    api_key="0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd"
)
server = OdooMCPServer(config)

# Or use environment variables
server = OdooMCPServer()
```
```

--------------------------------

### Update Record Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/tools.md

Use this snippet to update an existing record in Odoo. Provide the model, the record's ID, and the new values for the fields to be modified.

```json
{
  "model": "res.partner",
  "record_id": 42,
  "values": {
    "phone": "+1-555-9876",
    "email": "newemail@example.com"
  }
}
```

--------------------------------

### Run Code Style and Type Checks

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/CONTRIBUTING.md

Execute Ruff for formatting and linting, and ty for type checking. All checks must pass before submission.

```bash
uv run ruff check . && uv run ruff format --check . && uv run ty check .
```

--------------------------------

### OdooConfig Constructor

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Initializes the OdooConfig dataclass with all necessary connection and server settings. It validates all provided parameters upon creation.

```APIDOC
## OdooConfig Constructor

### Description
Initialize configuration with all connection and server settings. All settings are validated on initialization.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `url` | `str` | Yes | — | Odoo instance URL (must start with http:// or https://) |
| `api_key` | `Optional[str]` | * | `None` | API key for authentication (preferred over credentials) |
| `username` | `Optional[str]` | * | `None` | Odoo username (required with password if no API key) |
| `password` | `Optional[str]` | * | `None` | Odoo password (required with username if no API key) |
| `database` | `Optional[str]` | No | `None` | Database name (auto-detected if not set) |
| `log_level` | `str` | No | "INFO" | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
| `default_limit` | `int` | No | `10` | Default number of records returned per search |
| `max_limit` | `int` | No | `100` | Maximum allowed record limit per request |
| `max_smart_fields` | `int` | No | `15` | Maximum fields returned by smart field selection |
| `locale` | `Optional[str]` | No | `None` | Language/locale for Odoo responses (e.g., es_ES, fr_FR) |
| `transport` | `Literal["stdio", "streamable-http"]` | No | "stdio" | Transport protocol to use |
| `host` | `str` | No | "localhost" | Host to bind for HTTP transport |
| `port` | `int` | No | `8000` | Port to bind for HTTP transport |
| `session_idle_timeout` | `Optional[float]` | No | `None` | Seconds of inactivity before HTTP session eviction |
| `yolo_mode` | `str` | No | "off" | YOLO mode level: "off", "read", or "true" |
| `enable_method_calls` | `bool` | No | `False` | Enable call_model_method tool (requires yolo_mode="true") |
| `allowed_hosts` | `list[str]` | No | `[]` | Allowed Host headers for DNS rebinding protection |

*Either `api_key` OR both `username` and `password` are required. In YOLO mode, `username` is always required.

### Raises
- `ValueError`: If validation fails (missing required fields, invalid values, contradictory settings)

### Request Example
```python
from mcp_server_odoo.config import OdooConfig

config = OdooConfig(
    url="https://odoo.example.com",
    username="user",
    password="password",
    database="mydatabase",
    log_level="DEBUG",
    default_limit=50
)
```

### Response
None (Initialization does not return a value, but raises ValueError on failure)

### Response Example
None
```

--------------------------------

### Get Model Permissions

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/AccessController.md

Retrieves detailed CRUD permissions for a specific model. Use this to check read, write, create, and unlink access for a given model.

```python
perms = controller.get_model_permissions('sale.order')
if perms.can_read:
    print("Can read sales orders")
if perms.can_create:
    print("Can create sales orders")
```

--------------------------------

### Get Field Definitions for an Odoo Model

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/resources.md

Use this resource to retrieve the field definitions and metadata for a given Odoo model. The model name is specified in the URI.

```uri
odoo://res.partner/fields
```

```uri
odoo://sale.order/fields
```

```uri
odoo://product.product/fields
```

--------------------------------

### OdooConfig Initialization in YOLO Full Access Mode

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Initializes OdooConfig for YOLO mode with full read/write access. Specify URL, credentials, and set yolo_mode to 'true' along with enable_method_calls.

```python
config = OdooConfig(
    url="http://localhost:8069",
    username="admin",
    password="admin",
    yolo_mode="true",  # Full read/write
    enable_method_calls=True
)
```

--------------------------------

### ModelPermissions.can_perform Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/AccessController.md

Checks if a specific operation (read, write, create, unlink) is allowed for a given model's permissions. Returns True if allowed, False otherwise.

```python
permissions = ModelPermissions(
    model='res.partner',
    enabled=True,
    can_read=True,
    can_write=True,
    can_create=False,
    can_unlink=False
)
print(permissions.can_perform('read'))    # True
print(permissions.can_perform('create'))  # False
```

--------------------------------

### Get OdooMCPServer Health Status

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooMCPServer.md

Retrieve the current health status of the Odoo MCP server and its Odoo connection. This includes connection state, server version, and uptime.

```python
server = OdooMCPServer()
status = server.get_health_status()
print(f"Connected: {status['connected']}")
print(f"Server version: {status['version']}")
```

--------------------------------

### Get Default Field Values

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConnection.md

Use `default_get` to retrieve the default values for specified fields when creating a new record in an Odoo model. It can also accept a context dictionary.

```python
defaults = connection.default_get('sale.order', fields=['partner_id'])
print(f"Default partner: {defaults.get('partner_id')}")
```

--------------------------------

### AccessController Initialization

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/AccessController.md

Initializes the AccessController with Odoo connection details and optional parameters like database name and authentication method. Requires OdooConfig object.

```python
from mcp_server_odoo import OdooConfig, AccessController

config = OdooConfig(
    url="https://mycompany.odoo.com",
    api_key="0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd"
)
controller = AccessController(config, database="mycompany")
```

--------------------------------

### Get field definitions

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/resources.md

Retrieves the field definitions and metadata for a given Odoo model. The response is plain text detailing each field's name, type, label, and other relevant information.

```APIDOC
## GET odoo://{model}/fields

### Description
Get field definitions and metadata for an Odoo model.

### Method
GET

### Endpoint
odoo://{model}/fields

### Parameters
#### Path Parameters
- **model** (string) - Required - Odoo model name

### Response
Plain text formatted field list with metadata for each field.

**Field Information Includes:**
- Field name and type
- Human-readable label
- Whether field is required
- Whether field is read-only
- Related model (for relational fields)
- Field help text (if available)
```

--------------------------------

### Run OdooMCPServer with StdIO Transport

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooMCPServer.md

Run the Odoo MCP server using standard input/output transport, which is the default for Claude Desktop. Ensure asyncio is imported for execution.

```python
import asyncio
server = OdooMCPServer()
asyncio.run(server.run_stdio())
```

--------------------------------

### OdooConnection Constructor

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConnection.md

Initializes a new OdooConnection instance with the provided configuration, timeout, and an optional performance manager.

```APIDOC
## `__init__` Constructor

### Description
Initialize connection with configuration.

### Parameters
#### Path Parameters
- **config** (`OdooConfig`) - Required - OdooConfig object with connection parameters
- **timeout** (`int`) - Optional - Connection timeout in seconds (default: 30)
- **performance_manager** (`Optional[PerformanceManager]`) - Optional - Optional performance manager for optimizations

### Raises
- `OdooConnectionError`: If initial connection setup fails

### Example
```python
from mcp_server_odoo import OdooConfig, OdooConnection

config = OdooConfig(
    url="https://mycompany.odoo.com",
    api_key="0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd"
)
connection = OdooConnection(config, timeout=30)
```
```

--------------------------------

### Get Display Names for Records

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConnection.md

Use `name_get` to retrieve the display names for a list of record IDs from a specified Odoo model. It returns a list of tuples, where each tuple contains the record ID and its display name.

```python
names = connection.name_get('res.partner', [1, 2, 3])
for record_id, display_name in names:
    print(f"ID {record_id}: {display_name}")
```

--------------------------------

### VS Code (GitHub Copilot) Configuration

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/README.md

Configuration for VS Code with GitHub Copilot, using a different root key 'servers'. Requires ODOO_URL, ODOO_API_KEY, and ODOO_DB.

```json
{
  "servers": {
    "odoo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}
```

--------------------------------

### YOLO Full Access Configuration

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/configuration.md

Set environment variables for full access YOLO mode, enabling method calls. Use this for development environments.

```bash
export ODOO_URL=http://localhost:8069
export ODOO_USER=admin
export ODOO_PASSWORD=admin
export ODOO_YOLO=true
export ODOO_MCP_ENABLE_METHOD_CALLS=true
```

--------------------------------

### Post Message Example

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/tools.md

Use this snippet to post a message to a record's chatter. Specify the model, record ID, and the message body. Optionally, set the subtype, indicate if the body is HTML, and include partner or attachment IDs.

```json
{
  "model": "sale.order",
  "record_id": 42,
  "body": "Order confirmed and ready for shipping",
  "subtype": "comment"
}
```

--------------------------------

### Programmatic Configuration Loading in Python

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/configuration.md

Demonstrates how to load Odoo configuration programmatically in Python using the `mcp_server_odoo.config` module. Supports loading from environment, specific files, or directly creating config objects.

```python
from mcp_server_odoo.config import load_config, get_config, OdooConfig
from pathlib import Path

# Load from environment
config = load_config()

# Load from specific .env file
config = load_config(Path('/etc/mcp/.env'))

# Load from class method
config = OdooConfig.from_env()

# Create directly
config = OdooConfig(
    url="https://odoo.example.com",
    api_key="key...",
    database="example",
    yolo_mode="off"
)

# Get singleton instance
config = get_config()
```

--------------------------------

### Run YOLO Integration Tests

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/CONTRIBUTING.md

Execute YOLO integration tests, which connect to a vanilla Odoo instance without the MCP module.

```bash
uv run pytest -m "yolo" -v
```

--------------------------------

### Handle Authentication, Permission, and Not Found Errors

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/errors.md

Implement a try-catch block to handle specific MCP Server errors like AuthenticationError, MCPPermissionError, and NotFoundError. This allows for targeted error recovery, such as retrying with new credentials or logging permission issues.

```python
from mcp_server_odoo.error_handling import (
    AuthenticationError,
    MCPPermissionError,
    NotFoundError
)

try:
    result = connection.read('res.partner', [1])
except AuthenticationError as e:
    # Retry with new credentials
    reconnect()
except MCPPermissionError as e:
    # User lacks permissions
    log_permission_error(e.context)
except NotFoundError as e:
    # Record doesn't exist
    return None
```

--------------------------------

### Import Most Used Functions

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/INDEX.md

Imports functions for loading and accessing the server configuration, typically from environment variables.

```python
from mcp_server_odoo.config import (
    load_config,
    get_config,
)
```

--------------------------------

### Search Companies with Domain Filter

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Demonstrates searching for Spanish companies using OdooConnection with a domain filter and retrieving specific fields.

```python
from mcp_server_odoo import OdooConnection, OdooConfig

config = OdooConfig(url="...", api_key="...")
conn = OdooConnection(config)
conn.connect()

# Search Spanish companies
ids = conn.search('res.partner', [
    ['is_company', '=', True],
    ['country_id.code', '=', 'ES']
], limit=20)

records = conn.read('res.partner', ids, fields=['name', 'email', 'city'])
```

--------------------------------

### Initialize AccessController with YOLO Mode

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/AccessController.md

Initializes the AccessController in YOLO mode, bypassing all access control checks for development or testing. All operations are considered allowed.

```python
config = OdooConfig(
    url="http://localhost:8069",
    username="admin",
    password="admin",
    yolo_mode="true"  # Full access, no restrictions
)
controller = AccessController(config)
# All operations allowed, all models available
```

--------------------------------

### Configure Logging Level and Format

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/README.md

Shows how to configure the Odoo MCP server's logging level to DEBUG and enable structured JSON logs using environment variables.

```bash
# Debug level
export ODOO_MCP_LOG_LEVEL=DEBUG

# Structured JSON logs
export ODOO_MCP_LOG_JSON=true

# Log file
export ODOO_MCP_LOG_FILE=/var/log/mcp-server-odoo/server.log
```

--------------------------------

### OdooConfig Initialization in YOLO Read-Only Mode

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Initializes OdooConfig for YOLO mode with read-only access. Specify URL, credentials, database, and set yolo_mode to 'read'.

```python
config = OdooConfig(
    url="http://localhost:8069",
    username="admin",
    password="admin",
    database="demo",
    yolo_mode="read"  # Read-only access
)
```

--------------------------------

### OdooMCPServer Methods

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooMCPServer.md

Provides access to core methods for interacting with the Odoo MCP server, including health checks and running the server with different transports.

```APIDOC
## `get_health_status()`

### Description
Get the current health status of the server and its Odoo connection.

### Method
GET

### Endpoint
`/health`

### Parameters
None

### Returns
- `Dict[str, Any]`: Health status including connection state, version, and uptime

### Example
```python
server = OdooMCPServer()
status = server.get_health_status()
print(f"Connected: {status['connected']}")
print(f"Server version: {status['version']}")
```
```

```APIDOC
## `run_stdio()`

### Description
Run the server using standard input/output transport. This is the default transport method, often used by desktop applications.

### Method
N/A (Asynchronous Coroutine)

### Endpoint
N/A

### Parameters
None

### Raises
- `OdooConnectionError`: If connection to Odoo fails

### Example
```python
import asyncio
server = OdooMCPServer()
asyncio.run(server.run_stdio())
```
```

```APIDOC
## `run_http(host: str = "localhost", port: int = 8000)`

### Description
Run the server using HTTP transport with a streamable protocol. This allows for REST-style access and remote connectivity.

### Method
N/A (Asynchronous Coroutine)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `host` | `str` | `"localhost"` | Host to bind to |
| `port` | `int` | `8000` | Port to bind to |

### Raises
- `OdooConnectionError`: If connection to Odoo fails
- `OSError`: If port is already in use

### Example
```python
import asyncio
server = OdooMCPServer()
asyncio.run(server.run_http(host="0.0.0.0", port=8000))
```
```

--------------------------------

### OdooConfig Initialization with HTTP Transport

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/OdooConfig.md

Initializes OdooConfig for HTTP transport. Specify URL, API key, transport type, host, port, and allowed hosts.

```python
config = OdooConfig(
    url="https://company.odoo.com",
    api_key="key",
    transport="streamable-http",
    host="0.0.0.0",
    port=8000,
    allowed_hosts=["odoo.example.com", "localhost"]
)
```

--------------------------------

### list_resource_templates

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/tools.md

Lists available resource URI templates and their patterns.

```APIDOC
## Tool: list_resource_templates

List available resource URI templates and their patterns.

### Request Parameters

No parameters required.

```json
{}
```

### Response

```json
{
  "templates": [
    {
      "uri_template": "odoo://{model}/record/{id}",
      "description": "Retrieve a specific record by ID",
      "parameters": {
        "model": "Odoo model name",
        "record_id": "Record ID"
      },
      "example": "odoo://res.partner/record/42"
    }
  ],
  "enabled_models": ["res.partner", "sale.order", "..."],
  "total_models": 45,
  "note": "Resources don't support query parameters. Use tools for filtering."
}
```
```

--------------------------------

### AccessController Constructor

Source: https://github.com/ivnvxd/mcp-server-odoo/blob/main/_autodocs/api-reference/AccessController.md

Initializes the AccessController with Odoo connection details, optional database, cache TTL, and authentication method.

```APIDOC
## __init__ AccessController

### Description
Initialize access controller.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **config** (`OdooConfig`) - Required - OdooConfig with connection details and API key
- **database** (`Optional[str]`) - Optional - Resolved database name (for session auth)
- **cache_ttl** (`int`) - Optional - Cache time-to-live in seconds (default: 300)
- **auth_method** (`Optional[str]`) - Optional - Authentication method: 'api_key' or 'password'

### Request Example
```python
from mcp_server_odoo import OdooConfig, AccessController

config = OdooConfig(
    url="https://mycompany.odoo.com",
    api_key="0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd"
)
controller = AccessController(config, database="mycompany")
```
```