Odoo Assistant MCP Server

Un empleado virtual de Odoo a través del Model Context Protocol (MCP). Este servidor expone la lógica de negocio, los registros y los flujos de trabajo de Odoo a los LLM, permitiéndoles consultar, crear, actualizar y actuar sobre los datos de Odoo de forma segura.

Inicio rápido

1. Instalación

Ejecute el servidor directamente:

uvx odoo-assistant

O instálelo en su entorno:

uv pip install odoo-assistant

La instalación desde el código fuente para desarrollo sigue siendo posible:

uv pip install git+https://github.com/singleflo/odoo-assistant-mcp

2. Configurar variables de entorno

Se requieren dos variables; todo lo demás se descubre o tiene un valor predeterminado:

• ODOO_BASE_URL: La URL base de su instancia de Odoo (por ejemplo, https://mycompany.odoo.com).

• ODOO_API_KEY: La clave API de Odoo (Odoo 14+, generar en Ajustes > Usuarios > Claves API > Nueva). No se acepta una contraseña de cuenta: una clave es por usuario, con ámbito y revocable por sí misma.

Configuración opcional:

• ODOO_DB: El nombre de la base de datos. Se descubre automáticamente cuando la instancia sirve exactamente una base de datos; se requiere cuando sirve varias — el error las nombra todas.

• ODOO_USER: El inicio de sesión. Se descubre a partir de la clave a costa de hasta 59 viajes de ida y vuelta adicionales; la detección falla si el uid del propietario de la clave es 60 o superior. Configurarlo ahorra la sonda.

• ODOO_MCP_MAX_LEVEL: El nivel de seguridad más alto que este servidor puede ejecutar, de 0 a 4 (predeterminado: 3). Así es como hace que el servidor sea de solo lectura o le permite eliminar — consulte Elegir el límite máximo.

• ODOO_MCP_PROTECTED_HOSTS: Hosts separados por comas a los que este servidor se niega a escribir (vacío por defecto — ningún host está incluido en el paquete). Un host listado aún permite lecturas; escribir requiere ODOO_ALLOW_PROD_WRITE=yes como una anulación deliberada.

Related MCP server: mcp-server-odoo

Capa de seguridad

Cada escritura y acción pasa a través de un clasificador de seguridad dinámico antes de llegar a Odoo. Las operaciones se clasifican en niveles L0 a L5:

Elegir el límite máximo

ODOO_MCP_MAX_LEVEL establece el nivel más alto que este servidor puede ejecutar. Cada valor es acumulativo: permite su propio nivel y todo lo inferior:

Dos comportamientos son importantes de conocer antes de elegir un número:

• 5 no desbloquea L5. Ambas variantes de L5 se rechazan antes de que se lea el límite máximo. L5_PRIVATE se rechaza porque Odoo mismo rechaza todo método que comience con _, por lo que ningún límite podría entregarlo; L5_UNKNOWN se rechaza porque un método que nadie clasificó tiene, por definición, efectos no revisados. La forma de permitir tal método es agregarlo a WRITE_L1/L3/L4 en safety_layer.py — en código, revisado — nunca a través de la configuración.

• Un valor inválido rechaza el inicio. ODOO_MCP_MAX_LEVEL="O" genera una excepción en lugar de recurrir al valor predeterminado, porque el valor de respaldo es capaz de escribir: un error tipográfico no debe entregarle un servidor de escritura que creía que era de solo lectura.

El límite máximo se establece fuera de banda, por un humano, y se lee del entorno del proceso al inicio. El modelo que se ejecuta contra este servidor no puede elevarlo; cuando una llamada excede el límite máximo, la negativa nombra el nivel requerido, por lo que el agente puede explicar qué cambiaría la operación y dejar la decisión a usted.

Tenga en cuenta que esta es la autoridad de este servidor, no de la cuenta. Un agente con acceso a shell siempre puede eludir un servidor MCP invocando a Odoo directamente. Un límite que debe mantenerse independientemente del cliente pertenece a los derechos de acceso de Odoo del usuario al que pertenece la clave API, donde el servidor de Odoo lo aplica.

Soporte de versiones de Odoo

Odoo 14.0 es la versión mínima absoluta compatible porque este servidor se autentica solo mediante claves API, las cuales no existen en Odoo 13 o anterior.

Ruta de generación de clave API

Para generar una clave API, inicie sesión en su instancia de Odoo y navegue a: Preferencias / Mi perfil → Seguridad de la cuenta → Nueva clave API

Nota de transporte y desaprobación

El cliente detecta automáticamente si la API JSON-2 nativa está disponible en /json/2/<model>/<method> (que usa Authorization: bearer <API_KEY>) y recurre a XML-RPC si no lo está. Tenga en cuenta que XML-RPC y JSON-RPC están en desuso en Odoo 19 y se eliminarán en Odoo 22.

Fuentes

• Documentación de la API externa de Odoo 14.0 (introducción a las claves API)

• Documentación de la API externa de Odoo 19.0 (JSON-2)

• Documentación de la API RPC externa de Odoo 19.0 (desaprobación de XML-RPC)

• Política de soporte estándar y extendido de Odoo (cronogramas de soporte)

Herramientas y recursos

El servidor expone 19 herramientas y 2 tipos de recursos:

Herramientas

1. search_read: Buscar y leer registros en una sola llamada (Odoo search_read).

2. read_record: Leer un registro por id, siempre con campos nombrados.

3. count_records: Contar los registros que coinciden con un dominio (Odoo search_count).

4. instance_overview: Resumir la instancia conectada: versión, empresas, volúmenes por área, módulos internos, anomalías.

5. required_fields: Listar lo que Odoo exige antes de un create en un modelo, el valor predeterminado que aplicaría y cómo los registros existentes lo usan realmente.

6. create_record: Crear un registro, reutilizando una coincidencia existente cuando se proporciona unique_on.

7. write_record: Escribir valores de campo en un registro e informar qué cambió realmente.

8. run_action: Ejecutar un método de flujo de trabajo e informar el estado que dejó.

9. cancel_record: Cancelar un registro a través de action_cancel, siguiendo el asistente que devuelve.

10. notify_user: Notificar a los usuarios en el chatter de un registro. Interno por defecto.

11. create_activity: Programar una actividad: la única notificación que lleva una fecha límite.

12. download_docs: Guardar todos los documentos de un registro en disco, incluidos los archivos del chatter.

13. generate_pdf: Renderizar el PDF de un registro y devolver dónde se guardó.

14. list_message_targets: Listar quién puede recibir mensajes y dónde: usuarios internos con presencia (en línea/ausente/desconectado) y las conversaciones abiertas del llamante. Pregunte esto antes de enviar.

15. read_conversation: Leer una conversación de Discuss, de la más nueva a la más antigua.

16. send_direct_message: Enviar un mensaje 1-a-1 de Discuss que aparece en la bandeja de chat del usuario en tiempo real — sin correo electrónico, le llega independientemente de su configuración de notificaciones.

17. send_channel_message: Publicar en un canal de Discuss existente, rechazando una sala que contenga a un no empleado.

18. explore_module: Descubrir la estructura de un módulo interrogando la instancia en vivo.

19. list_known_modules: Listar los módulos que este servidor ha aprendido: nombre, fecha de generación, registros.

Las herramientas 10-11 (notify_user, create_activity) notifican SOBRE un registro y aterrizan en la campana de la bandeja de entrada; las herramientas 14-17 son conversaciones de Discuss que aterrizan en la bandeja de chat. "Enviar mensaje al usuario X" es el segundo tipo — send_direct_message, no notify_user.

Recursos

• odoo://skill: Acceder a las instrucciones de habilidad del asistente de Odoo.

• odoo://ref/*: Acceder a la documentación de referencia generada para los módulos explorados.

Ejemplos de configuración de host

Cada ejemplo a continuación incluye solo lo que importa: las dos variables requeridas, y el límite máximo — la única configuración que decide si este servidor puede escribir, hecha visible en el archivo que posee el humano. La base de datos y el inicio de sesión se descubren, y 3 es el valor predeterminado del límite máximo. Observe las comillas: los valores de entorno son cadenas.

Claude Desktop

Agregue esto a su claude_desktop_config.json:

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

Cursor

Agregue esto a su .cursor/mcp.json o configúrelo en la interfaz de configuración de Cursor:

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

VS Code Copilot

Agregue esto a su settings.json de VS Code:

{
  "mcp.servers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

opencode

Agregue esto a opencode.json o .opencode/opencode.json en su proyecto, o a ~/.config/opencode/opencode.json para que el servidor esté disponible en todas partes:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "odoo-assistant": {
      "type": "local",
      "enabled": true,
      "command": [
        "uvx",
        "odoo-assistant"
      ],
      "timeout": 120000,
      "environment": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

La forma de opencode difiere de los hosts anteriores en aspectos que rechaza directamente: la clave es mcp (no mcpServers), type es obligatorio, command es un único array que contiene el programa y sus argumentos (no hay args separado), y el bloque de entorno es environment (no env).

Establezca timeout deliberadamente. Su valor predeterminado es 5000 ms, y la primera llamada de una sesión paga la autenticación más, para instance_overview, docenas de viajes de ida y vuelta XML-RPC — cómodamente más de cinco segundos contra una instancia real.

opencode lee su configuración una vez al inicio y no la recarga en caliente, por lo tanto, cierre y reinicie después de editarla. Cualquier cosa que cambie aquí — el límite máximo incluido — surte efecto solo en el próximo inicio.

ChatGPT (Conectores personalizados)

Para conectar este servidor a ChatGPT mediante Conectores personalizados:

1. Vaya a Configuración → Conectores → Agregar conector.

2. Ingrese la URL del servidor o seleccione del Registry.

3. Ingrese sus credenciales de Odoo cuando se le solicite.

Hermes

Agregue el servidor usando la CLI de Hermes:

hermes mcp add odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_MCP_MAX_LEVEL=3 \
  --args run odoo-assistant

Los ejemplos omiten las variables opcionales. Establezca ODOO_DB cuando la instancia atienda varias bases de datos, ODOO_USER para omitir la sonda de uid, y ODOO_MCP_MAX_LEVEL para cambiar el límite máximo de su valor predeterminado de 3.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte el archivo LICENSE para más detalles.