odoo-devkit

Token-efficient MCP server for Odoo 17/18/19 development.

`odoo-devkit` gives AI assistants structured access to your Odoo codebase for discovery, search, model/view analysis, XML checks, and scaffolding patches.

Highlights

• Fast module and code discovery across addons roots
• Model surface inspection (fields, methods, views, actions, menus, security)
• View inheritance navigation (`find_view_chain`, inherited views, field usage)
• Patch scaffolding for common Odoo tasks (models, views, actions, menus, security, wizards, reports)
• XML validation for view structure and field references
• Web dashboard that starts with the MCP server (Serena-style flow)
• Layered config: global + project override

Requirements

• Python 3.10+
• `uv` (recommended)
• `ripgrep` (`rg`) for fast search

Install examples:

# Ubuntu/Debian
sudo apt install ripgrep

# macOS
brew install ripgrep

Installation

git clone https://github.com/VatsalChauhan36/odoo-devkit.git
cd odoo-devkit
uv sync
uv run odoo-devkit --help

Configuration

You can configure roots and defaults via environment variables, global config, and project config.

Config files (Serena-like)

• Global config: `~/.odoo-devkit/config.json`
• Project config: `/.odoo-devkit/project.json`

Effective config resolution:

1. Global config

2. Project override (if project root is detected)

Project root detection order:

1. `ODOO_MCP_PROJECT_ROOT`

2. nearest ancestor containing `.odoo-devkit/project.json`

3. nearest ancestor containing `.git`

Root paths priority

Addons roots are resolved with this priority:

1. `ODOO_MCP_ROOTS`

2. saved config (`roots` in global/project config)

Typical roots order:

1. Custom addons

2. Odoo server addons

3. Odoo base addons

Example:

export ODOO_MCP_ROOTS="/path/to/custom-addons:/path/to/odoo/addons:/path/to/odoo/odoo/addons"

Windows PowerShell:

$env:ODOO_MCP_ROOTS = "C:\custom-addons;C:\odoo\addons;C:\odoo\odoo\addons"

Optional docs search

To enable `search_odoo_docs`, set:

export ODOO_MCP_DOCS_PATH="/path/to/odoo/documentation"

Dashboard flow

The dashboard starts with the MCP server by default.

Saved settings include:

• `open_browser`
• `enable_dashboard`
• `dashboard_host`

CLI overrides:

uv run odoo-devkit --no-dashboard
uv run odoo-devkit --dashboard-host 0.0.0.0
uv run odoo-devkit --no-open-browser
uv run odoo-devkit --project-root /path/to/project

If browser auto-open is skipped (for example, headless Linux), use the MCP tool `open_dashboard`.

Screenshots

Then this preview will render automatically:

Deprecated CLI flags

These flags are intentionally kept for backward compatibility and are ignored:

• `--roots`
• `--config`

They emit warnings and do not affect runtime behavior.

MCP client setup

Claude Code

{
  "mcpServers": {
    "odoo-devkit": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/odoo-devkit",
        "odoo-devkit",
        "--project-root", "/path/to/your/project"
      ]
    }
  }
}

Cursor

{
  "mcpServers": {
    "odoo-devkit": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/odoo-devkit",
        "odoo-devkit",
        "--project-root", "/path/to/your/project"
      ]
    }
  }
}

Tool overview

Discovery & search

• `list_modules`
• `list_custom_modules`
• `get_module_manifest`
• `get_module_structure`
• `glob_odoo_files`
• `read_file_lines`
• `search_odoo_code`
• `search_odoo_docs`

Model and view analysis

• `inspect_model_surface`
• `find_model_definition`
• `get_model_fields`
• `find_method_definition`
• `find_view_definition`
• `find_inherited_views`
• `find_view_by_model`
• `find_view_chain`
• `find_field_in_views`
• `validate_view_xml`

Actions, menus, and security

• `find_action_by_model`
• `find_menu_hierarchy`
• `find_security_access_for_model`

Scaffolding (patch generation)

• `scaffold_model_patch`
• `scaffold_inherit_model_patch`
• `scaffold_view_inherit_patch`
• `scaffold_views_patch`
• `scaffold_action_patch`
• `scaffold_menu_patch`
• `scaffold_security_access_patch`
• `scaffold_record_rule_patch`
• `scaffold_wizard_patch`
• `scaffold_report_patch`
• `manifest_update_patch`
• `init_update_patch`

Runtime helpers

• `run_module_upgrade`
• `execute_rpc`
• `check_rpc_connection`
• `open_dashboard`

Recommended usage pattern

1. Start with `list_custom_modules` and `get_module_structure`

2. Narrow with `search_odoo_code` (`module_filter`, `glob`)

3. Use `inspect_model_surface` for model-level orientation

4. Use view tools for inheritance-aware XML navigation

5. Use scaffold tools to generate safe patches before applying

Troubleshooting

`No valid roots found`

Set `ODOO_MCP_ROOTS` or save roots in dashboard config (global/project).

`rg: command not found`

Install ripgrep (`ripgrep` package).

Dashboard did not open

• Check `open_browser` setting
• Use `--open-browser` to force when supported
• On headless Linux, open URL manually or call `open_dashboard`

MCP client cannot connect

• Verify path in `--directory`
• Re-run `uv sync`
• Run `uv run odoo-devkit --help` locally

License

MIT. See LICENSE.