Skip to content

mart337i/odoo-dev-mcp

BranchesTags

Repository files navigation

Odoo Development MCP Server

A Model Context Protocol (MCP) server for Odoo module development with AI assistance. Provides version-aware official documentation links (17.0, 18.0, 19.0), intelligent code generation, and development workflow automation.

🚀 Quick Start | 📖 OpenCode Setup | 🧪 Testing Guide | 🔧 Troubleshooting | 📋 Guides Index | 📝 Changelog

Features

  • 📚 Official Documentation Links: Version-aware links to Odoo's developer reference at https://www.odoo.com/documentation/<version>/developer/reference.html
  • 🧭 Skill-Informed Odoo Guardrails: Built-in guidance learned from mart337i/odoo-skills without requiring that repo at runtime
  • 🔧 Version-Aware Code Generation: All generated code includes version info and relevant documentation links
  • 🦉 OWL Frontend Scaffolds: Generate Odoo OWL components, client actions, field widgets, services, and frontend tests
  • 📋 Integrated Development Guidelines: Built-in Odoo coding standards and best practices enforcement
  • 💡 Smart Prompts: Guided workflows with rules-aware feature development, debugging, and upgrades
  • 🎯 Automatic Context: Generated code includes references to official Odoo documentation and development rules

Works Great With Odoo Skills

This MCP server pairs well with the companion Odoo skill set at mart337i/odoo-skills. Use those skills in your agent/client for deeper Odoo workflows like addon planning, migrations, code review, testing, OWL frontend work, and debugging. The MCP server does not require that repo at runtime; it only generates tools, guardrails, and references that complement skill-driven work.

Installation

Prerequisites

# Ensure Python 3.12+ is installed
python --version

# Install MCP CLI (if not already installed)
pip install "mcp[cli]"

For Claude Desktop

  1. Quick Install (Recommended):

    mcp install src/odoo_mcp/server.py --name "Odoo Dev"

  2. Manual Install:

    Edit your Claude Desktop config file:

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

    Add this configuration:

    {
  "mcpServers": {
    "odoo-dev": {
      "command": "python",
      "args": ["/absolute/path/to/odoo-dev-mcp/src/odoo_mcp/server.py"]
    }
  }
}

  3. Restart Claude Desktop

For OpenCode

📖 Complete OpenCode Setup Guide →

Quick setup - add to ~/.opencode/config.jsonc:

Option 1: Using uv (Recommended)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "odoo-dev": {
      "type": "local",
      "command": ["uv", "run", "/absolute/path/to/odoo-dev-mcp/src/odoo_mcp/server.py"],
      "enabled": true,
      "environment": {
        "PATH": "/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin",
        "ODOO_SOURCE": "/path/to/odoo",
        "ODOO_BASE_COMMAND": "/path/to/odoo/odoo-bin -c /path/to/odoo.conf --addons-path=/path/to/addons",
        "ODOO_TOOL_README": "/path/to/local-development/README.md"
      }
    }
  }
}

First, install dependencies:

cd /path/to/odoo-dev-mcp
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

Option 2: Using Python directly

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "odoo-dev": {
      "type": "local",
      "command": ["python3", "/absolute/path/to/odoo-dev-mcp/src/odoo_mcp/server.py"],
      "enabled": true,
      "environment": {
        "PYTHONPATH": "/absolute/path/to/odoo-dev-mcp"
      }
    }
  }
}

See examples/opencode.jsonc.example for a complete working example.

Note: Requires pip install mcp first.

Then use in OpenCode:

Search Odoo documentation for "fields.Command"
Set Odoo version to 19.0
Get Odoo local context
Get documentation URL for reference/backend/orm
Create model library.book with fields: name, author
Get development guidelines

Local Odoo Environment Context

Configure these optional environment variables so the MCP can point agents at your local Odoo source, command template, and local development guide:

export ODOO_SOURCE=/path/to/odoo
export ODOO_BASE_COMMAND="/path/to/odoo/odoo-bin -c /path/to/odoo.conf --addons-path=/path/to/addons"
export ODOO_TOOL_README=/path/to/local-development/README.md

Use get_odoo_local_context() or odoo://local/context to inspect the configured values. The server treats ODOO_BASE_COMMAND as a command template only; agents should still ask before running commands that touch a database or local service.

See OPENCODE_SETUP.md for complete guide with examples, troubleshooting, and workflows.

Quick Start

1. Test the Server

python test_server.py

You should see all tests pass with ✓ marks.

2. Basic Usage in Claude/OpenCode

# Set your Odoo version
Set Odoo version to 19.0

# Create a module
Create an Odoo module called "library_management" with display name "Library Management"

# Create a model
Create a model library.book with fields: name (char), author_id (many2one to res.partner), isbn (char)

# Generate views
Create a form view for library.book with fields: name, author_id, isbn

# Add security
Create security rules for library.book in module library_management

# Search official documentation catalog
Search Odoo documentation for "computed fields"

Available Tools

Version Management

  • set_odoo_version(version) - Switch between 17.0, 18.0, 19.0
  • get_current_version() - Check current version

Documentation & Guidelines

  • get_odoo_local_context(include_readme_excerpt) - Show configured ODOO_SOURCE, ODOO_BASE_COMMAND, ODOO_TOOL_README, source hints, and command templates
  • get_documentation_url(path, version) - Get an official Odoo documentation URL
  • search_documentation(query, version) - Search the built-in official reference catalog and return Odoo documentation links
  • get_development_guidelines(context) - Get context-specific coding guidelines
    • Contexts: general, models, views, security, all
  • explain_odoo_error(error_text, version, context) - Diagnose patterned Odoo tracebacks with root cause, inspection steps, and docs links
  • plan_odoo_feature(description, module_name, version) - Create a skill-informed Odoo implementation plan with security, view, test, and docs guidance
  • plan_owl_feature(description, module_name, integration_type, target_bundle, version) - Plan Odoo OWL frontend work with asset, registry, service, and test guardrails
  • layout_module_dependencies(module_name, features, models, integrate_with, explicit_dependencies) - Infer and order manifest dependencies for an Odoo module

Code Generation (Version-Aware)

  • create_odoo_module(name, display_name, description, ...) - Generate module structure with version-specific manifest
  • create_odoo_model(model_name, description, fields, inherit) - Create Python models with ORM documentation links
  • create_odoo_view(model_name, view_type, fields_to_display, view_name, parent_menu) - Generate safer XML views with version-aware tree/list handling and no fake menu parent
  • create_security_rules(model_name, module_name, groups) - Create security config with security documentation
  • create_base_automation(...) - Generate version-aware base.automation and linked ir.actions.server XML for automated actions
  • create_upgrade_script(module_name, from_version, to_version, ...) - Generate version-aware pre-migration.py, post-migration.py, and end-migration.py scaffolds with verified odoo.upgrade.util helper examples
  • create_owl_component(component_name, module_name, ...) - Generate Odoo OWL JS/XML/SCSS component scaffolds and manifest asset entries
  • create_owl_client_action(action_name, module_name, ...) - Generate an OWL client action, registry.category("actions") registration, and ir.actions.client XML
  • create_owl_field_widget(widget_name, module_name, ...) - Generate an OWL field widget using standardFieldProps and the fields registry
  • create_owl_service(service_name, module_name, ...) - Generate a frontend service using the services registry and explicit dependencies
  • create_owl_test(component_name, module_name, ...) - Generate an Odoo Hoot frontend test scaffold and test asset entry

Development Prompts

  • develop_odoo_feature(description) - Guided feature development
  • debug_odoo_error(error, context) - Error debugging assistance
  • upgrade_odoo_module(module, from_version, to_version) - Migration guidance
  • review_odoo_code(code) - Code review with best practices

Resources

Access Odoo documentation and development rules:

Documentation:

  • odoo://docs/19.0/index - Official developer reference index
  • odoo://docs/19.0/reference/backend/orm - ORM reference URL and metadata
  • get_documentation_url("reference/backend/security", "19.0") - Official Odoo security documentation URL

Local Odoo Context:

  • odoo://local/context - Configured local Odoo source path, base command, and tooling README excerpt

Development Rules:

  • odoo://rules/all - All development guidelines
  • odoo://rules/clean-code - Clean code principles
  • odoo://rules/odoo-development - Odoo-specific conventions

Examples

Complete Module Creation

# In Claude/OpenCode:

1. Set Odoo version to 19.0
2. Plan the feature: task management with priorities and deadlines
3. Layout dependencies for task management with chatter and automations
4. Create module "task_manager" with display name "Task Manager"
5. Create model task.task with fields:
   - name (char, required)
   - description (text)
   - priority (selection: low, medium, high)
   - assigned_to (many2one: res.users)
   - deadline (date)
6. Create form view for task.task
7. Create list view for task.task
8. Create security rules for task.task
9. Create an automated action that assigns overdue tasks

Automated Action Example

Create a base automation for task.task that runs on create or write, watches stage_id and deadline, and executes Python code.

The helper will include base_automation manifest dependency guidance and version-specific notes for time-based triggers.

OWL Frontend Examples

Plan an OWL client action for an equipment rental dashboard in equipment_rental.

Create an OWL component called Rental Dashboard in equipment_rental with title prop, orm service, and local state.

Create an OWL field widget called Rental Badge in equipment_rental for char and selection fields.

The OWL helpers generate Odoo asset bundle entries, @odoo/owl imports, registry wiring, XML templates, SCSS, and frontend test guidance.

Migration And Error Examples

Create upgrade scripts for equipment_rental from 17.0 to 19.0, renaming old_stage_id to stage_id and old XML IDs.

The migration scaffold includes phase-specific odoo.upgrade.util examples for model, field, XML ID, module, SQL, and ORM data-migration helpers.

Explain this Odoo error: odoo.tools.convert.ParseError: while parsing views/equipment_views.xml, External ID not found in the system

Field Types Examples

All Odoo field types are supported:

fields = [
    {"name": "name", "type": "Char", "required": True},
    {"name": "description", "type": "Text"},
    {"name": "amount", "type": "Float"},
    {"name": "quantity", "type": "Integer"},
    {"name": "active", "type": "Boolean"},
    {"name": "date", "type": "Date"},
    {"name": "partner_id", "type": "Many2one", "comodel_name": "res.partner"},
    {"name": "line_ids", "type": "One2many", "comodel_name": "model.line", "inverse_name": "parent_id"},
    {"name": "tag_ids", "type": "Many2many", "comodel_name": "model.tag"},
    {"name": "state", "type": "Selection", "selection": "[('draft', 'Draft'), ('done', 'Done')]"}
]

Development

Run Tests

uv run python -m tests.test_server

Test with MCP Inspector

mcp dev odoo_mcp_server.py

Architecture

odoo_mcp_server.py
├── Resources (Documentation)
│   ├── Official Odoo reference URL catalog
│   ├── Version-specific links
│   └── Topic search
├── Tools (Code Generation)
│   ├── Module scaffolding
│   ├── Model definitions
│   ├── View generation
│   └── Security rules
└── Prompts (Workflows)
    ├── Feature development
    ├── Error debugging
    ├── Module upgrades
    └── Code review

Development Guidelines

The server includes comprehensive Odoo development guidelines that are automatically applied:

Built-in Rules

  • Clean Code Principles - General software engineering best practices
  • Odoo Conventions - Odoo-specific naming, structure, and coding standards
    • Module structure and naming
    • Model and field naming conventions
    • View architecture standards
    • Security rules patterns
    • ORM best practices
    • Performance optimization tips

Rules Integration

All code generation tools automatically include:

  • ⚠️ Naming convention warnings
  • 📋 Context-specific guidelines
  • 🔗 Links to relevant rules sections
  • ✅ Best practice recommendations

Access Guidelines

# Get general guidelines
get_development_guidelines("general")

# Get model-specific rules
get_development_guidelines("models")

# Access all rules
View resource: odoo://rules/all

Documentation Strategy

The server points to official Odoo documentation instead of vendoring stale local copies. The base URL pattern is:

https://www.odoo.com/documentation/<version>/developer/reference.html

Common topic links follow the same structure:

https://www.odoo.com/documentation/19.0/developer/reference/backend/orm.html
https://www.odoo.com/documentation/19.0/developer/reference/backend/security.html
https://www.odoo.com/documentation/19.0/developer/reference/frontend/owl_components.html

The repository still contains docs/ as a legacy local fallback, but MCP tools prefer official documentation URLs.

docs/
├── 17.0/ (legacy fallback)
├── 18.0/ (legacy fallback)
└── 19.0/ (legacy fallback)

rules/
├── clean-code.mdc
└── odoo-development.mdc

Supported Platforms

  • ✅ Windows, macOS, Linux
  • ✅ Claude Desktop
  • ✅ OpenCode (VS Code extension)
  • ✅ Any MCP-compatible client

Requirements

  • Python 3.12+
  • MCP SDK 1.4.1+
  • FastMCP

Troubleshooting

Server not showing in Claude?

  1. Check config file is valid JSON
  2. Verify absolute paths
  3. Restart Claude Desktop completely

Import errors?

pip install "mcp[cli]"

Documentation not found?

Use get_documentation_url() or odoo://docs/<version>/index. The server returns official Odoo URLs and does not require local docs for normal use.

Tips

  1. Always set the Odoo version first - All code generation adapts to the selected version
  2. Review development guidelines - Use get_development_guidelines() for context-specific rules
  3. Follow naming conventions - Generated code includes rules warnings for common mistakes
  4. Use descriptive model names - e.g., library.book (with dots), not lib_b (with underscores)
  5. Check rules in generated code - Each tool output includes relevant naming and coding rules
  6. Search before asking - Use search_documentation() for official reference links
  7. Test incrementally - module → models → views → security
  8. Review code against rules - Use the review_odoo_code prompt for rule compliance checks

License

MIT License

Contributing

Contributions welcome! This server follows clean code principles and Odoo best practices.

About

A MCP server for odoo development

Resources

Readme

License

MIT license
Activity

Stars

17 stars

Watchers

1 watching

Forks

9 forks
Report repository

Releases 2

v1.2.0 Latest
May 8, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages