Saltar a contenido

Odoo Tools: Introducción

MCP-Odoo-Tools es un plugin de Claude Code que unifica el acceso a Odoo en una sola instalación: un servidor MCP (superficie principal) y una CLI de respaldo. Funciona con Odoo Community, Enterprise y online (SaaS), desde la versión 10 hasta la 19, gracias a una capa de compatibilidad que resuelve automáticamente los nombres de modelos y campos que cambian entre versiones. Sus skills y comandos también cargan en Cowork y en Claude chat, pero las herramientas de Odoo solo corren en Claude Code (ver Dónde funciona).

Online/SaaS: se requiere plan con API externa

El acceso RPC externo solo está disponible en suscripciones de Odoo Online con API habilitada (planes Custom). En planes sin API externa la conexión falla aunque las credenciales sean correctas: verifica con odoo_version y consulta Solución de problemas si ves errores de conexión. En Odoo Online la única credencial que funciona es una API key.

Empieza aquí

Instala el plugin y ejecuta /odoo-tools:odoo-setup-mcp: la ruta guiada de configuración, entrenamiento, uso y despliegue. ¿Sin un Odoo para practicar? /odoo-tools:deploy-local levanta un sandbox local.

Novedades en v1.6.0: una sola copia, la correcta, y cada comando en su lugar

  • Comandos de instalación por superficie: /plugin install dentro de Claude Code, o claude plugin install ... --scope user en una terminal. Instala una sola copia. Ver Instalación.
  • odoo_version nombra la copia que responde (bloque plugin), y la ruta guiada y /odoo-tools:odoo-doctor encuentran una segunda copia o una anterior a la 1.5.0 y se detienen ahí. Ver Dos copias de odoo-tools.
  • Windows sin python3: claude mcp list reporta el servidor como Failed to connect con Connection closed, y nada menciona a Python. La solución está en Solución de problemas.
  • El estado not_started de la app: /odoo-tools:odoo-doctor y la ruta guiada reconocen el estado not_started con el motivo user_config_unsupported como el caso de Cowork y Claude chat: no es un error, y ninguna actualización lo cambia. Te llevan a una sesión local de la pestaña Code o a Claude Code; Claude Code no necesita permisos de administrador. Ver Solución de problemas.
  • El sandbox local trae una API key para el plugin en Odoo 14.0 a 19.0. Ver Despliegue local.
  • Siguen siendo 28 herramientas. En Odoo 10 a 12, la política rechaza también las claves de un objeto pasado por posición que no son campos del modelo ni claves de contexto permitidas, así que cambia el digest de la política. Ver Política de permisos.

Novedades en v1.5.1: honesto en cada superficie, con diagnóstico local

  • Primero, dónde corre Claude. Si las herramientas de Odoo no están cargadas, /odoo-tools:odoo-doctor no corre comandos, no revisa Python y no da consejos del lado de Odoo: en Cowork y Claude chat te lleva a la pestaña Code de Claude Desktop o a Transgenia. Las skills, comandos y agentes que usan las herramientas de Odoo empiezan con la misma revisión.
  • Diagnóstico local y reporte de soporte. El servidor guarda en tu equipo un registro pequeño, solo de metadatos, y el doctor termina con un reporte sin keys, URLs, logins ni datos de registros que puedes enviar a Transgenia. Ver Soporte.
  • Un hook de inicio de sesión que no lee ninguna opción del plugin ni credencial, y un servidor que ya no lee ODOO_HTTP_BEARER. Ver Seguridad.
  • Siguen siendo 28 herramientas. Los perfiles readonly, standard y builder rechazan un poco más (las reglas de contexto se aplican también a un objeto pasado por posición, que Odoo 10 a 12 toman como contexto), así que cambia el digest de la política. Ver Política de permisos.

Novedades en v1.5.0: permisos seguros por defecto

El servidor MCP aplica una política de permisos encima de los derechos del usuario de Odoo. El perfil por defecto, standard, lee, crea, actualiza y corre métodos de negocio, pero no borra, no hace cambios estilo Studio, no envía correo ni SMS (las notas internas sí) y no lee secretos guardados; lista 25 de las 28 herramientas. Cada llamada deja una línea en un registro de auditoría local. Para conservar el comportamiento de la 1.4, pon la opción Permission profile en full.

Está construido y mantenido por Transgenia, partner registrado de Anthropic (tier Registered). Es un proyecto open-source independiente con licencia MIT: no es un producto certificado ni de primera parte de Anthropic. Está publicado en el directorio de plugins de Anthropic, donde cada versión nueva llega cuando un revisor de Anthropic la aprueba, así que el directorio puede ofrecer una versión anterior a la que describe este manual. Instala una sola copia, desde el marketplace de Transgenia (ver Instalación).

Dónde funciona

Entorno Servidor MCP (las herramientas de Odoo) Skills y comandos Agentes y hooks
Claude Code en tu equipo (terminal, VS Code, JetBrains, una sesión local de la pestaña Code de Claude Desktop) Sí Sí Sí
Claude Code en una sesión en la nube (pestaña Code de Claude Desktop, claude.ai/code) No Sí Sí
Cowork (Claude Desktop) No Sí Sí
Claude chat (claude.ai web, escritorio, móvil) No Sí No

Las herramientas de Odoo corren como un servidor MCP local por stdio (python3 3.9+) en el equipo donde corre Claude Code, y los datos de conexión (URL, base de datos, login, API key) se capturan en las opciones del plugin de Claude Code (userConfig en plugin.json): Claude Code te los pide al habilitar el plugin, o los recibe con claude plugin configure.

Según la matriz de soporte de plugins de Anthropic, Cowork no pide valores de opciones e ignora un servidor MCP que usa una opción sin valor por defecto (la URL, la base, el login y las credenciales de este plugin no lo tienen), y Claude chat ignora el servidor MCP local de un plugin. En esas apps el plugin se instala y sus skills y comandos cargan, pero no alcanzan Odoo sin las herramientas. Es el comportamiento previsto de esas apps, no una instalación rota.

Claude Desktop nombra este caso, para el servidor de este plugin, con el estado not_started y el motivo user_config_unsupported: es igual en macOS que en Windows, no es una falla del plugin ni de la app, y ninguna actualización del plugin lo cambia.

Nada está mal con tu cuenta, tu Odoo ni tu Python. Abre una sesión local de la pestaña Code de Claude Desktop (o Claude Code en una terminal, VS Code o JetBrains): el plugin que instalaste en tu cuenta de Claude aparece ahí sincronizado cuando entras con la misma cuenta. O pide a Transgenia una configuración asistida: dev@transgenia.org · WhatsApp +52 55 8034 0405.

Una sesión en la nube de Claude Code (el entorno en la nube de la pestaña Code, o claude.ai/code) es otro caso: el plugin se sincroniza desde tu cuenta, pero sus opciones no. Claude Code las guarda en el equipo donde las capturas (la API key y la contraseña, en el almacén seguro de credenciales de ese equipo), así que el servidor no arranca en la nube. Usa una sesión local.

Cowork y Claude chat sí aceptan conectores MCP que agregas tú: un servidor MCP remoto accesible por una URL https o, en la app de escritorio, una extensión de escritorio. Este plugin no provee ninguno de los dos: sus herramientas de Odoo necesitan el servidor local. Si en claude.ai ves la fila odoo con la leyenda Runs in each session y un panel vacío, ver Solución de problemas.

Qué resuelve

Los nombres de modelos y campos de Odoo cambian entre versiones:

  • account.invoice se fusionó en account.move en la v13 (fusión, no renombre: en v10-12 coexisten como facturas vs. asientos; ver Compatibilidad).
  • Los campos analíticos cambiaron en la v16 (analytic_account_id → analytic_distribution).
  • Los modelos de paquetes cambiaron en la v19 (stock.quant.package → stock.package).
  • El método name_get desapareció en la v18 (se lee display_name).
  • Odoo Online adelanta cambios en sus líneas saas~N.M: uom_po_id ya no existe desde saas~18.1, antes que en la 19.0.
  • La propia API RPC cambia desde la v19: /xmlrpc y /jsonrpc quedan obsoletos y Odoo 22 (y Odoo Online saas~21.1) los retiran; su reemplazo es JSON-2, que el servidor usa automáticamente cuando hay una API key.

Además, Enterprise incluye modelos que Community no tiene. Para un agente de IA, cada una de estas diferencias es un punto de falla silencioso: llama al nombre antiguo, el ERP responde con un error, y el agente no distingue si es un problema de permisos, de red o de versión.

Este plugin absorbe esas diferencias detrás de una sola superficie de herramientas estable, para que no tengas que ramificar tu código por versión.

Las dos superficies

Superficie Cuándo usarla Requisitos
Servidor MCP (recomendada) Uso normal desde Claude Code: 28 herramientas (incluidas 6 para Odoo Online; 25 listadas con el perfil por defecto standard) + capa de compatibilidad completa, por JSON-2, JSON-RPC o XML-RPC, con una política de permisos y registro de auditoría python3 3.9+ (solo biblioteca estándar; no instala nada)
CLI de respaldo Cuando no puedes correr el servidor MCP, o para acceso por lotes desde scripts Node.js 18+

Alcance (público vs. privado)

Este es el núcleo genérico público: habla con Odoo y nada más. Desde la v1.5.0, una política de permisos genérica y declarativa forma parte del núcleo público. Los flujos de aprobación, los motores de localización (por ejemplo, la facturación electrónica por país), los respaldos, la IA documental y otros motores específicos de un cliente quedan deliberadamente fuera de este repositorio y se ofrecen como parte de las implementaciones supervisadas de Transgenia.

Siguiente paso

Continúa con la Instalación o salta directo al Inicio rápido guiado.

Soporte de implementación

¿Necesitas ayuda para conectarlo a tu Odoo o una integración de IA/ERP a la medida? Transgenia ofrece servicios de implementación de IA y Odoo. Escríbenos a dev@transgenia.org.