Odoo MCP Server — Agentic Edition

An enterprise-grade Model Context Protocol (MCP) server for interacting with Odoo ERP through AI assistants. Unlike a traditional database connector, this server is designed as an agentic bridge: it teaches the AI how to navigate Odoo, understand its business logic, and perform complex data analysis.

---

Why Agentic Edition?

• Guided Workflows (Prompts) — Native instructions that teach your AI how to audit inventory, analyse sales, or review security permissions step by step, without writing prompts from scratch.
• Native BI — Optimised support for read_group and advanced analytical operations, allowing the AI to generate financial reports or KPIs instantly.
• Deep Introspection — Tools that grant the AI X-ray vision: discover available action buttons, inspect view XML architectures, evaluate security rules — reducing hallucinations to a minimum.
• Zero extra dependencies — Uses only Python stdlib (urllib, json, csv, xml) plus the mcp package. No requests, no odoorpc.
• Built-in Security — Uses Odoo's own XML-RPC layer; the MCP server cannot bypass permissions the user doesn't already have.

---

Installation

# Recommended — isolated and fast
uv tool install odoo-mcp-server-conn

# Standard
pip install odoo-mcp-server-conn

---

Configuration

Environment variables

Variable	Required	Description
ODOO_URL	✅	Your Odoo URL (e.g. http://localhost:8069)
ODOO_DB	✅	Database name
ODOO_USERNAME	✅	User login or email
ODOO_PASSWORD	✅	Password or API Key (strongly recommended)
MCP_AUTH_CACHE_TTL	❌	Seconds before re-authenticating (default: 300)

Tip: Always prefer an API Key over a plain password. Generate one in Odoo under Settings → Users → Your User → API Keys.

---

Claude Code (CLI)

Run this command once — it stores the configuration permanently for the current project:

claude mcp add odoo-server \
  --env ODOO_URL=http://localhost:8069 \
  --env ODOO_DB=my_database \
  --env ODOO_USERNAME=admin \
  --env ODOO_PASSWORD=my_api_key \
  -- odoo-mcp-server-conn

Verify the connection inside Claude Code:

/mcp

<details> <summary>Project-scoped config — share with your team via <code>.mcp.json</code></summary>

Add --scope project to create a .mcp.json at the repository root that your whole team can use. Each developer supplies their own credentials via environment variables or CI secrets.

claude mcp add odoo-server \
  --scope project \
  --env ODOO_URL=http://localhost:8069 \
  --env ODOO_DB=my_database \
  --env ODOO_USERNAME=admin \
  --env ODOO_PASSWORD=my_api_key \
  -- odoo-mcp-server-conn

</details>

---

Claude Desktop

Locate your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following block:

{
  "mcpServers": {
    "odoo-server": {
      "command": "odoo-mcp-server-conn",
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "my_database",
        "ODOO_USERNAME": "admin",
        "ODOO_PASSWORD": "my_api_key"
      }
    }
  }
}

---

VS Code (Copilot / Cline / Roo Code)

Add to your .vscode/mcp.json (workspace-level) or user MCP settings:

{
  "servers": {
    "odoo-server": {
      "type": "stdio",
      "command": "odoo-mcp-server-conn",
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "my_database",
        "ODOO_USERNAME": "admin",
        "ODOO_PASSWORD": "my_api_key"
      }
    }
  }
}

<details> <summary>Cline / Roo Code — <code>cline_mcp_settings.json</code></summary>

{
  "mcpServers": {
    "odoo-server": {
      "command": "odoo-mcp-server-conn",
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "my_database",
        "ODOO_USERNAME": "admin",
        "ODOO_PASSWORD": "my_api_key"
      }
    }
  }
}

</details>

---

Cursor IDE

1. Go to Settings → Features → MCP.
2. Click Add new server → type command.
3. Command: odoo-mcp-server-conn.
4. Add each environment variable in the Env vars section.

---

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "odoo-server": {
      "command": "odoo-mcp-server-conn",
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "my_database",
        "ODOO_USERNAME": "admin",
        "ODOO_PASSWORD": "my_api_key"
      }
    }
  }
}

---

Tools

CRUD — Core operations

Tool	Odoo method	Description
search_records	search	Return IDs matching a domain filter
read_records	read	Read fields from records by ID
search_read_records	search_read	Search + read in one optimised call
create_record	create	Create a new record
update_record	write	Update existing records
delete_record	unlink	Delete records ⚠️
count_records	search_count	Count without loading records (fast)

Introspection — understand the data model in real time

Tool	Description
get_model_fields	Live schema of any model (types, relations, required flags)
get_view_architecture	Final merged XML of a view (form / tree / kanban / search)
get_workflow_states	States, stages, and transition buttons of a model
get_action_buttons	All buttons in a view with visibility conditions and groups
get_related_records	Auto-resolved Many2one / One2many / Many2many relations
get_security_rules	ACL and ir.rule records for a model
explain_domain	Translates an Odoo domain filter into plain English

BI & Analytics

Tool	Description
read_group	GROUP BY with sums, counts, averages. Supports :month / :year date grouping
export_to_csv	Export records to a CSV string (up to 1 000 rows)
get_available_reports	List PDF / HTML reports available for a model

Wildcard

Tool	Description
execute_method	Call any public Odoo method (e.g. action_confirm, button_validate)

---

Guided Prompts (pre-trained workflows)

Invoke these prompts directly from your AI client to start a structured analysis:

Prompt	What it does
analyze_sales	Sales KPIs — revenue trend, top customers, conversion rate
diagnose_inventory	Low-stock products, stuck transfers, warehouse utilisation
audit_permissions	Cross-reference security groups with ACL, flag over-privileged users
financial_overview	Cash flow overview — AR, AP, invoicing by period

---

Resources (navigable URIs)

The AI can query these URIs directly as if browsing the ERP:

URI	Description
odoo://models	Master list of all models installed in the instance
odoo://fields/{model}	Data dictionary for a specific model
odoo://record/{model}/{id}	Complete record sheet
odoo://search/{model}/{domain}	Instant search, e.g. odoo://search/res.partner/[["is_company","=",true]]

---

Security

• The server operates entirely through Odoo's XML-RPC layer — it cannot bypass any permission the authenticated user doesn't already have in the ERP.
• No raw SQL, no forced commits, no ORM bypass.
• Credentials are read exclusively from environment variables — never hardcoded.

License: MIT