Odoo MCP Server (OdooConsole)

Odoo MCP Server

Un servidor MCP (Model Context Protocol) que conecta agentes de IA a instancias de Odoo ERP. Funciona con Claude Code, Cursor, Windsurf y cualquier cliente compatible con MCP.

Soporta Odoo 17-18 (JSON-RPC) y Odoo 19+ (JSON-2 API) — detecta automáticamente el mejor protocolo.

Inicio Rápido

# Run directly (uv handles dependencies automatically)
ODOO_URL=https://my.odoo.com ODOO_DB=mydb ODOO_USER=admin ODOO_PASSWORD=secret \
  uv run odoo_mcp_server.py

No se necesita virtualenv ni pip install — el script tiene metadatos en línea que uv resuelve automáticamente.

Configurar en Claude Code

Añade a .mcp.json de tu proyecto:

{
  "mcpServers": {
    "odoo": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "your-password"
      }
    }
  }
}

O para Odoo 19+ con autenticación mediante clave API:

{
  "mcpServers": {
    "odoo": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USER": "admin",
        "ODOO_API_KEY": "your-api-key"
      }
    }
  }
}

Configurar en Cursor / Windsurf

Añade a ~/.cursor/mcp.json o equivalente:

{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "your-password"
      }
    }
  }
}

Variables de Entorno

Variable	Requerido	Descripción
ODOO_URL	Sí	URL de la instancia de Odoo
ODOO_DB	Sí	Nombre de la base de datos
ODOO_USER	Sí	Nombre de usuario de inicio de sesión
ODOO_PASSWORD	Uno de estos	Contraseña (Odoo 17-18)
ODOO_API_KEY	requerido	Clave API (Odoo 19+, preferida)
ODOO_READONLY	No	Establecer a true para deshabilitar todas las operaciones de escritura

Modo de Solo Lectura

Establece ODOO_READONLY=true para deshabilitar las herramientas create, update, delete y execute. Útil para navegar de forma segura en instancias de producción:

{
  "mcpServers": {
    "odoo": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://production.odoo.com",
        "ODOO_DB": "prod",
        "ODOO_USER": "readonly-user",
        "ODOO_PASSWORD": "secret",
        "ODOO_READONLY": "true"
      }
    }
  }
}

Herramientas Disponibles

CRUD Básico

Herramienta	Descripción
odoo_search_read	Consultar registros con filtros de dominio, selección de campos, paginación
odoo_search_count	Contar registros coincidentes sin obtener datos
odoo_export	Exportación masiva de hasta 2000 registros por llamada para hojas de cálculo
odoo_create	Crear nuevos registros
odoo_update	Actualizar registros existentes por ID
odoo_delete	Eliminar registros por ID
odoo_execute	Ejecutar cualquier método del modelo (action_confirm, action_post, etc.)

Descubrimiento

Herramienta	Descripción
odoo_list_models	Descubrir modelos disponibles con filtro de palabras clave
odoo_get_fields	Inspeccionar definiciones de campos para cualquier modelo
odoo_doctor	Diagnósticos de salud (versión, módulos, usuarios, crons, errores)
odoo_connection_info	Mostrar detalles de conexión actuales

Personalización de Modelos

Herramienta	Descripción
odoo_model_info	Obtener metadatos completos del modelo en una sola llamada — campos, vistas, acciones, valores predeterminados, orden de clasificación
odoo_set_default	Establecer, actualizar o borrar el valor predeterminado de un campo (maneja ir.default + codificación JSON)
odoo_get_view	Obtener el XML de la vista de formulario/árbol/búsqueda completamente renderizado (fusionado)
odoo_modify_action	Cambiar el dominio, contexto, orden de clasificación, límite o modos de vista de una acción de ventana

Ejemplo de Uso

Una vez configurado, pregunta a tu agente de IA:

• "Lista todas las órdenes de venta de este mes"
• "Muéstrame los campos en res.partner"
• "Crea un nuevo contacto llamado Acme Corp"
• "Ejecuta una verificación de salud en la instancia de Odoo"
• "Exporta todos los productos a una hoja de cálculo"
• "Confirma la orden de venta 42"

Ejemplos de Personalización de Modelos

• "¿Cuál es el orden de clasificación predeterminado para sale.order?"
• "Cambia la política de facturación predeterminada en productos a 'delivery'"
• "Muéstrame la vista de formulario para res.partner"
• "¿Qué acciones de ventana existen para account.move? Cambia el orden predeterminado a fecha descendente"
• "Lista todos los campos personalizados en res.partner"
• "¿Qué campos son obligatorios en sale.order?"

Herramientas de Personalización de Modelos — Referencia Detallada

odoo_model_info

Devuelve todo sobre un modelo en una sola llamada, eliminando la necesidad de múltiples consultas exploratorias.

odoo_model_info(model="sale.order")

Devuelve:

• default_order — el atributo _order del modelo (por ejemplo, "date_order desc, id desc")
• rec_name — el campo utilizado para el nombre mostrado en los menús desplegables
• field_count — número total de campos
• fields_by_type — recuento de campos agrupados por tipo (many2one: 12, char: 8, ...)
• custom_fields — campos creados por el usuario (prefijo x_ o state=manual)
• relational_fields — todos los Many2one, One2many, Many2many con sus destinos
• required_fields — campos que deben completarse
• views — vistas base (formulario, árbol, búsqueda) con IDs y prioridades
• actions — acciones de ventana con su dominio, contexto y modos de vista
• defaults — valores ir.default actuales establecidos para los campos de este modelo

odoo_set_default

Gestiona los valores predeterminados de campos mediante ir.default con codificación JSON adecuada. La fuente más común de errores de agente cuando se hace manualmente.

# Set global default
odoo_set_default(model="product.template", field_name="invoice_policy", value="delivery")

# Set user-specific default
odoo_set_default(model="sale.order", field_name="warehouse_id", value=2, user_id=5)

# Remove a default
odoo_set_default(model="product.template", field_name="invoice_policy", value=null)

La herramienta:

1. Encuentra el field_id en ir.model.fields (valida que el campo exista)
2. Codifica el valor en JSON automáticamente
3. Crea o actualiza el registro ir.default
4. Devuelve los valores antes/después para confirmación

odoo_get_view

Devuelve el XML de la vista completamente renderizado después de aplicar toda la herencia — lo que el usuario realmente ve, no los fragmentos crudos almacenados en ir.ui.view.

odoo_get_view(model="sale.order", view_type="form")
odoo_get_view(model="res.partner", view_type="tree")
odoo_get_view(model="account.move", view_type="search")

Devuelve:

• arch — el XML fusionado completo
• view_id — el ID de la vista base
• fields_in_view — lista de nombres de campos presentes en la vista

odoo_modify_action

Cambia cómo aparece un modelo en la interfaz de usuario modificando su acción de ventana (ir.actions.act_window).

# List actions for a model (read-only)
odoo_modify_action(model="sale.order")

# Change default sort order
odoo_modify_action(action_id=42, order="date_order desc")

# Change default filter and page size
odoo_modify_action(action_id=42, domain="[['state','=','sale']]", limit=200)

# Add default grouping via context
odoo_modify_action(action_id=42, context="{'group_by': 'partner_id'}")

La herramienta devuelve valores antes/después para que puedas verificar qué cambió.

Cómo Funciona

AI Agent (Claude, Cursor, etc.)
    ↕ MCP Protocol (stdio)
Odoo MCP Server
    ↕ JSON-RPC / JSON-2 API
Odoo Instance

El servidor se autentica una vez al inicio y mantiene una conexión persistente. Todas las herramientas usan la misma sesión autenticada.

Requisitos

• Python 3.11+
• uv (recomendado) o pip install fastmcp httpx

Licencia

MIT