Getting Started¶

This guide walks you through a complete setup — from installing the Odoo module to your first AI query. It takes about 10 minutes.

Step 1 — Install the Odoo Module¶

Requirements¶

Odoo 19 (Community or Enterprise)
Python 3.10+
The defusedxml Python package

Install defusedxml in the same Python environment that runs your Odoo server:

pip install defusedxml

If you use a virtual environment (common on self-hosted installs):

source /path/to/your/odoo/venv/bin/activate
pip install defusedxml

Install the module¶

Copy the alpenglow_mcp folder into one of your Odoo addons paths.
Restart the Odoo server.
Go to Apps, search for Alpenglow MCP Connector, and click Install.

Step 2 — Run the Setup Wizard¶

The setup wizard walks you through enabling MCP access, selecting models, creating an API credential, and generating a ready-to-paste client configuration.

Opening the wizard¶

From the menu: Settings > Alpenglow MCP > Setup Wizard (requires MCP Manager group).
From General Settings: Settings > General Settings, scroll to the Alpenglow MCP section, click Setup Wizard under Quick Actions.

Wizard steps¶

1. Enable MCP Access — Toggle on. Optionally check Default Read-Only to start with a conservative posture.

2. Select Models — Pick the Odoo models AI assistants can access. Common choices:

Model	Description
`res.partner`	Contacts
`sale.order`	Sales Orders
`product.product`	Products
`account.move`	Invoices

You can add or remove models later from the Resources menu.

3. Create API Credential — Give your credential a name (e.g., "Claude Desktop — John") and choose Full Access or Read-Only scope. Click Next to generate the API key.

Copy your API key immediately

The API key is only shown once during generation. If you lose it, you'll need to create a new credential.

4. Connect Your Client — Select your AI client type. The wizard generates a JSON configuration block with your server URL, database name, and API key pre-filled. Keep this page open — you'll paste this config in the next step.

Step 3 — Install the Bridge¶

The bridge (alpenglow-mcp-bridge) is a small Python package that runs locally on your workstation. It translates between the MCP stdio protocol that AI assistants speak and HTTP requests to your Odoo server.

The easiest way to install and run the bridge is with uv, a fast Python package manager. You do not need Python installed separately — uv handles it automatically.

macOS / LinuxWindows

Open a terminal and run:

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

Close and reopen your terminal (or run source ~/.bashrc / source ~/.zshrc), then verify:

uvx --version

Open PowerShell and run:

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

Close and reopen PowerShell, then verify:

uvx --version

Note

You do not need to run pip install alpenglow-mcp-bridge manually. The uvx command downloads and runs the bridge automatically on first use.

Step 4 — Connect Your AI Client¶

Paste the JSON configuration from the setup wizard (Step 2) into your AI client. The config tells the client how to launch the bridge with the correct server URL, database, and API key.

The generated config looks like this (the wizard fills in the actual values):

{
  "mcpServers": {
    "alpenglow-odoo": {
      "command": "uvx",
      "args": [
        "alpenglow-mcp-bridge",
        "--url", "https://your-odoo.com",
        "--db", "your-database",
        "--token", "YOUR_API_KEY_HERE"
      ]
    }
  }
}

Claude Desktop¶

The config file location depends on your operating system:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows (standard)	`%APPDATA%\Claude\claude_desktop_config.json`
Windows (Microsoft Store)	`%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude-3p\claude_desktop_config.json`

Tip

In Claude Desktop, go to Settings (gear icon) > Developer > Edit Config to open the correct file automatically.

If the file already has other MCP servers configured, add the "alpenglow-odoo" block inside the existing "mcpServers" object.

Restart Claude Desktop after saving (fully quit and reopen — it only reads the config at startup). You should see "alpenglow-odoo" listed as a connected MCP server.

Claude Code¶

Run this command in your terminal (replace the values with your own):

claude mcp add alpenglow-odoo -- uvx alpenglow-mcp-bridge \
    --url https://your-odoo.com \
    --db your-database \
    --token YOUR_API_KEY_HERE

Restart Claude Code. Run /mcp to verify the server is connected.

Cursor¶

Go to Settings > MCP Servers and paste the JSON configuration block. Restart Cursor.

VS Code¶

Create or edit .vscode/mcp.json in your workspace and paste the JSON configuration block. Reload the VS Code window.

Step 5 — Verify It Works¶

Open your AI client and try a natural language query:

"What Odoo models are available?"
"Search for the first 5 contacts"
"Describe the sale.order model"

If the AI returns data from your Odoo instance, you're connected.

Bridge Reference¶

The alpenglow-mcp-bridge package supports the following options:

Flag	Env Variable	Description
`--url`	`ALPENGLOW_URL`	Odoo instance URL (required), e.g. `https://your-odoo.com`
`--db`	`ALPENGLOW_DB`	Odoo database name (required if the server hosts multiple databases)
`--token`	`ALPENGLOW_TOKEN`	Alpenglow API key (required)

Environment variables can be used instead of command-line flags. Flags take precedence if both are provided.

Available Tools¶

The bridge registers 9 tools with the AI client:

Tool	Description
`alpenglow_list_models`	List all available Odoo models and their permissions
`alpenglow_describe`	Get full schema for a model (fields, types, relationships)
`alpenglow_search`	Search records with domain filters, pagination, and sorting
`alpenglow_read`	Read specific records by ID
`alpenglow_create`	Create one or more records
`alpenglow_update`	Update records by ID
`alpenglow_delete`	Delete records by ID
`alpenglow_aggregate`	Run reporting queries (count, sum, avg, group_by, trend, etc.)
`alpenglow_execute`	Call a whitelisted ORM method on a model