✨ 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?"

"Analyze my requirements: I run a bakery with 3 locations and need inventory and POS"

"Generate a custom addon for recipe management with ingredients tracking"

OdooForge turns natural language into Odoo operations. From spinning up Docker containers to generating complete custom addons — with built-in domain knowledge that helps AI assistants make better decisions.

🚀 Quick Start

1. Install

pip install odooforge

2. Initialize Workspace

odooforge init

This scaffolds everything you need in the current directory:

.
├── CLAUDE.md                  # AI assistant context
├── .env                       # Connection settings (fill in your details)
├── .claude/skills/            # Claude Code skills (/odoo-brainstorm, /odoo-architect, /odoo-debug)
├── docker/
│   ├── docker-compose.yml     # Odoo 18 + PostgreSQL 17
│   └── odoo.conf
├── addons/                    # Your custom Odoo modules
├── .cursor/mcp.json           # Cursor MCP config
├── .windsurf/mcp.json         # Windsurf MCP config
└── .gitignore

3. Start Odoo

# Edit .env with your connection details, then:
cd docker && docker compose up -d

4. Start Coding

Open the workspace in your AI editor. The MCP configs are already set up — your assistant has access to all 79 OdooForge tools.

Ask your AI assistant to run odoo_diagnostics_health_check to verify everything is connected.

Updating Your Workspace

After upgrading OdooForge (pip install --upgrade odooforge), update workspace template files to the latest versions:

odooforge init --update

This overwrites skills, configs, and Docker files with the latest versions. Your .env is never overwritten.

⚙️ 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.

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"
      }
    }
  }
}

🛠 79 Tools Across 20 Categories

📖 Full Tool Reference →

🧠 Domain Knowledge & AI Guidance

OdooForge includes built-in domain knowledge that helps AI assistants make informed decisions:

MCP Resources (6)

Structured knowledge accessible via odoo:// URIs:

MCP Prompts (4)

Guided workflows that provide step-by-step instructions:

Claude Code Skills (3)

Slash-command skills for Claude Code users (installed to .claude/skills/ by odooforge init):

🍳 Industry Recipes

One-command setup for common business types:

"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/>79 tools · 6 resources · 4 prompts]

    MCP --> Planning[Planning Layer]
    MCP --> Workflows[Workflow Layer]
    MCP --> Tools[Core Tool Layer]
    MCP --> Knowledge[Knowledge Layer]

    subgraph Planning[Layer 3: Planning]
        direction LR
        P1[Requirement Analysis]
        P2[Solution Design]
        P3[Plan Validation]
    end

    subgraph Workflows[Layer 2: Workflows]
        direction LR
        W1[Business Setup]
        W2[Feature Builder]
        W3[Dashboard]
        W4[Integration]
    end

    subgraph Tools[Layer 0: Core Tools]
        direction LR
        T1[Records]
        T2[Modules]
        T3[Schema]
        T4[Views]
        T5[+ 13 more]
    end

    subgraph Knowledge[Layer 1: Domain Knowledge]
        direction LR
        K1[Module KB]
        K2[Blueprints]
        K3[Patterns]
    end

    subgraph Codegen[Code Generation]
        direction LR
        C1[Model Gen]
        C2[View Gen]
        C3[Security Gen]
    end

    Workflows --> Codegen
    Tools --> Conn[Connections]

    subgraph Conn[Connections]
        direction LR
        RPC[XML-RPC]
        Docker[Docker]
        PG[PostgreSQL]
    end

    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/
├── cli.py                    # CLI entry point — server, init, init --update
├── init.py                   # Workspace initializer — scaffolds configs, skills, Docker
├── server.py                 # MCP server — 79 tools, 6 resources, 4 prompts
├── 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 (20 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
│   ├── planning.py           # Requirements analysis & solution design
│   ├── workflows.py          # Business setup & feature creation
│   ├── codegen.py            # Addon code generation
│   └── ...
├── knowledge/                # Domain knowledge (Layer 1)
│   ├── knowledge_base.py     # Singleton KB with modules, blueprints, patterns
│   └── data/                 # Structured knowledge data
├── planning/                 # Planning engine (Layer 3)
│   ├── requirement_parser.py # NL → structured requirements
│   └── solution_designer.py  # Requirements → implementation plan
├── workflows/                # Workflow orchestration (Layer 2)
│   ├── setup_business.py     # Full business deployment plans
│   ├── create_feature.py     # Custom feature step plans
│   ├── create_dashboard.py   # Dashboard creation plans
│   └── setup_integration.py  # Integration setup plans
├── codegen/                  # Code generation engine
│   ├── addon_builder.py      # Orchestrates full addon generation
│   ├── manifest_gen.py       # __manifest__.py generation
│   ├── model_gen.py          # Python model file generation
│   ├── view_gen.py           # XML view generation
│   └── security_gen.py       # Access rules & security groups
├── 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 (564 tests)
uv run pytest tests/ -v

# Run the server locally
uv run odooforge

See CONTRIBUTING.md for detailed development guidelines.

📚 Documentation

📄 License

AGPL-3.0 — use it however you want.