odooforge 0.1.8

AI-First ERP Configuration Engine — MCP server for Odoo 18

🔨 OdooForge

AI-First ERP Configuration Engine — MCP Server for Odoo 18

Give AI assistants complete control over Odoo 18 instances via Model Context Protocol.
71 tools. 16 categories. Zero clicking through menus.

Getting Started · Tool Reference · Architecture · Contributing

---

✨ What Can It Do?

"Start an Odoo instance and create a database called myshop"

"Install Sales, CRM, and Inventory modules"

"Add a custom loyalty tier field to res.partner as a selection"

"Create an automation that sends a welcome email for new contacts"

"Run the restaurant recipe to set up a full POS system"

"Show me the invoice report template and add a custom footer"

"Run a health check — are there any issues?"

OdooForge turns natural language into Odoo operations. It handles everything from spinning up Docker containers to modifying QWeb report templates.

🚀 Quick Start

1. Install

# Using pip
pip install odooforge

# Or run directly with uvx (no install needed)
uvx odooforge

2. Configure Your MCP Client

Add to your Claude Desktop or Cursor config:

{
  "mcpServers": {
    "odooforge": {
      "command": "uvx",
      "args": ["odooforge"]
    }
  }
}

3. Start Odoo

# Docker Compose included — Odoo 18 + PostgreSQL 17
docker compose -f docker/docker-compose.yml up -d

Create a .env file (see .env.example) or set environment variables:

ODOO_URL=http://localhost:8069
ODOO_DEFAULT_DB=odoo
ODOO_ADMIN_USER=admin
ODOO_ADMIN_PASSWORD=admin

That's it. Ask your AI assistant to run odoo_diagnostics_health_check to verify everything is connected.

⚙️ Configuration

OdooForge can be configured via environment variables. When running as an MCP server, pass these in your mcp.json or claude_desktop_config.json.

Variable	Description	Default
ODOO_URL	URL of the Odoo instance	http://localhost:8069
ODOO_DEFAULT_DB	Database to connect to by default	odoo
ODOO_ADMIN_USER	Admin username (for RPC)	admin
ODOO_ADMIN_PASSWORD	Admin password	admin
ODOO_MASTER_PASSWORD	Master password (for DB creation)	admin
POSTGRES_HOST	PostgreSQL host	localhost
POSTGRES_PORT	PostgreSQL port	5432
POSTGRES_USER	PostgreSQL user	odoo
POSTGRES_PASSWORD	PostgreSQL password	odoo
DOCKER_COMPOSE_PATH	Path to docker-compose.yml (optional)	Auto-detected

MCP Client Config (mcp.json)

Option 1: Using uvx (Recommended)

This runs the latest published version of OdooForge isolated from your system.

{
  "mcpServers": {
    "odooforge": {
      "command": "uvx",
      "args": ["odooforge"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DEFAULT_DB": "odoo",
        "ODOO_ADMIN_USER": "admin",
        "ODOO_ADMIN_PASSWORD": "my_admin_password",
        "ODOO_MASTER_PASSWORD": "my_master_password",
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "odoo",
        "POSTGRES_PASSWORD": "my_postgres_password"
      }
    }
  }
}

Option 2: Using Local Project (Development)

If you have customized OdooForge in a local virtual environment:

{
  "mcpServers": {
    "odooforge": {
      "command": "/path/to/your/venv/bin/odooforge",
      "args": [],
      "env": {
        "ODOO_ADMIN_PASSWORD": "secure_password"
      }
    }
  }
}

🛠 71 Tools Across 16 Categories

Category	#	Tools	Docs
Instance	5	start · stop · restart · status · logs	→
Database	6	create · list · backup · restore · drop · run_sql	→
Records	6	search · read · create · update · delete · execute	→
Snapshots	4	create · list · restore · delete	→
Modules	6	list_available · list_installed · info · install · upgrade · uninstall	→
Models	3	list · fields · search_field	→
Schema	5	field_create · field_update · field_delete · model_create · list_custom	→
Views	5	list · get_arch · modify · reset · list_customizations	→
Reports	6	list · get_template · modify · preview · reset · layout_configure	→
Automation	5	list · create · update · delete · email_template_create	→
Network	3	expose · status · stop	→
Import	3	preview · execute · template	→
Email	4	configure_outgoing · configure_incoming · test · dns_guide	→
Settings	4	settings_get · settings_set · company_configure · users_manage	→
Knowledge	3	module_info · search · community_gaps	→
Recipes	2	list · execute	→
Diagnostics	1	health_check	→

📖 Full Tool Reference →

🍳 Industry Recipes

One-command setup for common business types:

Recipe	Modules	What It Sets Up
🍕 Restaurant	POS, Kitchen, Inventory, HR	Table management, kitchen printing, food categories
🛒 eCommerce	Website, Payments, Delivery, CRM	Online shop, cart, checkout, wishlists
🏭 Manufacturing	MRP, Quality, Maintenance	Work centers, BoM, production planning
💼 Services	Project, Timesheets, CRM, Sales	Billable projects, task stages, invoicing
🏪 Retail	POS, Inventory, Loyalty	Barcode scanning, stock alerts, loyalty programs

"Run the restaurant recipe in dry-run mode first, then execute it"

🏗 Architecture

graph TB
    AI[AI Assistant<br/>Claude / Cursor / etc.] -->|MCP Protocol| MCP[OdooForge MCP Server<br/>71 tools registered]

    MCP --> Tools[Tool Layer]
    Tools --> Conn[Connection Layer]

    subgraph Tools[16 Tool Modules]
        direction LR
        T1[Records]
        T2[Modules]
        T3[Schema]
        T4[Views]
        T5[Reports]
        T6[+ 11 more]
    end

    subgraph Conn[Connections]
        direction LR
        RPC[XML-RPC Client<br/>Odoo API]
        Docker[Docker Client<br/>Container Mgmt]
        PG[PostgreSQL Client<br/>Direct SQL]
    end

    subgraph Utils[Utilities]
        direction LR
        Val[Validators]
        XPath[XPath Builder]
        QWeb[QWeb Builder]
        Cache[State Cache]
    end

    Tools --> Utils

    Conn --> Odoo[Odoo 18<br/>Docker Container]
    Conn --> DB[(PostgreSQL 17<br/>Docker Container)]

    style AI fill:#5A67D8,color:#fff
    style MCP fill:#714B67,color:#fff
    style Odoo fill:#714B67,color:#fff
    style DB fill:#336791,color:#fff

src/odooforge/
├── server.py                 # MCP server — all 71 tools registered
├── config.py                 # Environment configuration
├── connections/
│   ├── docker_client.py      # Docker Compose management
│   ├── xmlrpc_client.py      # Odoo XML-RPC interface
│   └── pg_client.py          # PostgreSQL direct connection
├── tools/                    # One file per tool category (16 files)
│   ├── records.py            # CRUD operations
│   ├── modules.py            # Module lifecycle
│   ├── schema.py             # Custom fields & models
│   ├── views.py              # View inheritance & XPath
│   ├── reports.py            # QWeb report templates
│   ├── automation.py         # Automated actions
│   └── ...
├── utils/                    # Shared utilities
│   ├── validators.py         # Input validation
│   ├── errors.py             # Custom error hierarchy
│   ├── xpath_builder.py      # XPath expression builder
│   ├── qweb_builder.py       # QWeb template helpers
│   └── response_formatter.py # Consistent response formatting
└── verification/             # Post-operation verification
    ├── state_cache.py        # Live model/field cache
    └── verify_*.py           # Category-specific verifiers

🔒 Safety Features

OdooForge is designed to be safe for AI-driven operations:

• 🔄 Snapshots — Create backups before risky operations. Restore instantly.
• ✅ Confirmation guards — Destructive actions (delete, drop, uninstall) require confirm=true.
• 🏷 Namespace enforcement — Custom fields must start with x_, custom models with x_. No accidental core modifications.
• 🔍 Post-operation verification — Module installs, field creation, and view modifications are verified after execution.
• 👁 Dry-run modes — Recipes and imports can be previewed before execution.
• 📋 Input validation — Model names, field names, SQL queries, and domains are validated before execution.

🧪 Development

# Clone and install
git clone https://github.com/hamzatrq/odoo-forge.git
cd odooforge
uv sync --group dev

# Run tests (212+ tests)
uv run pytest tests/ -v

# Run the server locally
uv run odooforge

See CONTRIBUTING.md for detailed development guidelines.

📚 Documentation

Document	Description
Getting Started	Installation, first run, connecting to MCP
Configuration	Environment variables, Docker setup
Tool Reference	All 71 tools with parameters and examples
Architecture	System design and data flow
Industry Recipes	Pre-built setup recipes
Contributing	Development setup and guidelines
Changelog	Version history

📄 License

AGPL-3.0 — use it however you want.