Inicio rápido: la ruta guiada¶

Empieza aquí: /odoo-tools:odoo-setup-mcp

Desde la v1.3.0 el plugin tiene una sola ruta guiada. Ejecuta /odoo-tools:odoo-setup-mcp (o su atajo /setup-odoo-tools): detecta lo que ya tienes y te acompaña, una pregunta a la vez, por cinco fases:

1 Configuración → 2 Verificación → 3 Entrenamiento → 4 Uso diario → 5 Despliegue

Al inicio de cada fase te muestra dónde vas. Esta página resume la ruta por si prefieres hacerla a mano.

Novedades en v1.6.0

En el Paso 0, una respuesta de odoo_version sin bloque policy detiene la ruta: respondió una copia anterior a la 1.5.0. En Claude Code, la ruta corre una vez la revisión de copias, y la revisión de opciones después de guardar.
En el Paso 0b, la ruta reconoce el estado not_started con el motivo user_config_unsupported como el caso de Cowork y Claude chat, te ofrece una sesión local de la pestaña Code (una sesión en la nube no tiene tus opciones) y te dice que Claude Code no necesita permisos de administrador.
En el Paso 3, la ruta pregunta primero para qué es la conexión, y en Odoo Online sugiere la base de datos a partir del subdominio.
La revisión inicial busca también git. En Windows, después de instalar Claude Code, Git o Python, abres una ventana nueva de PowerShell.
La Fase 5 da el comando de instalación de cada superficie: dentro de Claude Code o en una terminal.

Novedades en v1.5.1

En el Paso 0b, si las herramientas de Odoo no están cargadas, la ruta no corre comandos ni revisa Python hasta saber dónde usas Claude. En Cowork, una versión de Python leída ahí pertenece a su máquina virtual, no a tu equipo.
/odoo-tools:odoo-doctor empieza por esa misma revisión y termina con un reporte de soporte que puedes enviar a Transgenia.

Novedades en v1.5.0

La configuración incluye dos opciones nuevas: Permission profile (standard por defecto) y Permission policy file (opcional). Ver Política de permisos.
En el entrenamiento, el ejercicio de escritura archiva el contacto de prueba en lugar de borrarlo, porque standard no borra; el ejercicio estilo Studio necesita el perfil builder.
El despliegue recomienda standard (o readonly) en producción y parte del archivo de ejemplo endurecido cuando el usuario de Odoo es administrador.

Corre la ruta en Claude Code

La ruta configura y usa las herramientas de Odoo, que solo corren en Claude Code en tu equipo (terminal, VS Code, JetBrains o una sesión local de la pestaña Code de Claude Desktop). En Cowork y en Claude chat la skill carga, pero las herramientas no: la ruta lo detecta en el Paso 0b y te ofrece el camino que funciona. Ver Dónde funciona.

Fase 1: Configuración¶

La ruta te pregunta cuál es tu caso:

Conectar mi Odoo (producción o pruebas): los pasos 0-4 de abajo.
No tengo un Odoo para practicar / no quiero tocar producción: levanta un sandbox local de Odoo Community con /odoo-tools:deploy-local (Enterprise y Online no los puede proveer Transgenia). Ver Despliegue local.
No puedo instalar Python 3.9+: el servidor MCP en contenedor (/odoo-tools:deploy-local, modo contenedor) o la CLI de respaldo.

Paso 0: Detectar lo que ya tienes¶

Primero revisa su lista de herramientas, sin ejecutar nada. Si odoo_version no está, el servidor MCP no corre en esta superficie: pasa al Paso 0b antes de cualquier comando de shell. Si está, la llama una vez y lee la respuesta antes de decir nada:

Sin policy ni note: respondió un odoo-tools anterior a la 1.5.0, sin política de permisos; suele ser una segunda copia, instalada desde otro lugar. La ruta se detiene ahí: nada de entrenamiento, uso diario ni escrituras, y te ayuda a dejar una sola copia actual.
Con note: la política de permisos está bloqueada. La nota nombra la opción o el archivo que corregir; no es una conexión que funcione.
plugin: la versión de odoo-tools que respondió y su copia instalada (plugin@marketplace). Te la muestra.

Si responde bien, con un bloque policy, las opciones del plugin ya están configuradas: te muestra la versión, la edición y la copia, y te ofrece saltar al entrenamiento, al uso diario o al despliegue. (No lee variables ODOO_* ni archivos de credenciales de tu equipo para averiguarlo.)

Cuando odoo_version responde, esto es Claude Code en tu equipo, y la ruta corre una vez la revisión de copias, aunque todo funcione: dos copias de odoo-tools pueden estar activas a la vez, y entonces el diálogo de opciones y las herramientas pueden ser de copias distintas. Te muestra la salida tal cual: nombra la copia que conservar y da los comandos exactos que quitan las demás (o que actualizan una copia antigua del marketplace de Transgenia), que tú corres en una terminal (PowerShell o Terminal), nunca como comandos /plugin, antes de reiniciar Claude Code. En Cowork nunca los corre: ahí sus comandos llegan a una máquina virtual, no a tu equipo. Ver Dos copias de odoo-tools.

Donde puede correr comandos, también revisa si python3 (3.9 o superior), git y docker están disponibles, para saber si en las fases siguientes aplica la ruta de Python o la del contenedor.

Paso 0b: ¿Están cargadas las herramientas de Odoo?¶

Solo cuando odoo_version no existe como herramienta. No empieza por Python. Te pregunta dónde usas Claude: 1) Claude Code, 2) Cowork o 3) Claude chat. Si describes un panel vacío en la fila odoo con la leyenda Runs in each session, en la pestaña Connectors del plugin, estás en 2 o 3. También si la app muestra el servidor del plugin con el estado not_started y el motivo user_config_unsupported: es el nombre que Cowork y Claude chat dan a este caso, igual en macOS que en Windows, no es una falla del plugin ni de la app, y ninguna actualización del plugin lo cambia.

Claude Code: si la sesión misma corre en la nube de Anthropic (una sesión en la nube de la pestaña Code, o Claude Code en la web), las opciones que guardaste en tu equipo no están ahí, así que el servidor no puede arrancar: la ruta te ofrece una sesión local, como en las opciones de 2 o 3, y se detiene. Si no, el servidor no arrancó; las causas habituales son opciones obligatorias vacías (URL, base de datos, login) o una segunda copia del plugin. Si puede correr comandos, corre la revisión de copias del Paso 0 y, cuando nombra la copia que conservar, la revisión de opciones de esa copia (Claude Code 2.1.285 o posterior; la salida nunca muestra la key). Actúa sobre lo que lista: las opciones que faltan se capturan en el diálogo de opciones, que abres dentro de Claude Code con /plugin configure <id>. Si falta python3, ninguna de las dos revisiones corre: la ruta lee directamente claude plugin list --json (más de un id odoo-tools@... habilitado aquí, o una versión anterior a la 1.5.0, es el problema; un id listado en dos alcances es una sola copia, y una entrada de proyecto o local cuenta solo en su propia carpeta, su projectPath o una carpeta dentro de ella) y pasa a revisar Python. Después reinicias Claude.
Cowork o Claude chat: esas apps no corren el servidor MCP local del plugin ni tienen un formulario para sus opciones. La instalación está bien, y nada está mal con tu cuenta, tu Odoo ni tu Python; la ruta te ofrece:
1. Claude Code en tu equipo (recomendado): una terminal, VS Code, JetBrains o una sesión local de la pestaña Code de Claude Desktop (no una sesión en la nube, que no tiene las opciones guardadas en tu equipo). Un plugin instalado en tu cuenta de Claude aparece ahí como plugin sincronizado al iniciar la siguiente sesión si entras a Claude Code (2.1.273 o posterior) con esa cuenta de claude.ai; si no aparece, /reload-plugins o los comandos de Instalación. Claude Code no necesita permisos de administrador: su instalador nativo lo deja en tu carpeta personal. En un plan Team o Enterprise, tu organización decide qué plugins recibes y si la pestaña Code ofrece sesiones locales.
2. Solo en Cowork: la CLI de respaldo, cuando la sesión puede correr Node, alcanzar tu Odoo y tú puedes editar su .env. Usa una API key dedicada, de mínimo privilegio y de corta duración. No aplica a Claude chat, que no tiene un lugar seguro para capturar la key.
3. Transgenia para una configuración asistida (ver Soporte).

En esas apps la ruta no te lleva por Python ni por las opciones del plugin, porque ahí no pueden funcionar. En Cowork, los comandos de shell corren en una máquina virtual, no en tu equipo: una versión de Python leída ahí no dice nada de tu equipo. Tampoco da consejos del lado de Odoo (plan, API key, base de datos) hasta que las herramientas corren y Odoo rechaza la conexión. Si el contexto de Claude trae una línea que empieza con odoo-tools session diagnostics:, la escribió en tu equipo el hook de inicio de sesión del plugin, y /odoo-tools:odoo-doctor la convierte en un reporte de soporte que puedes enviar a Transgenia.

Paso 1: Elegir la superficie¶

Servidor MCP (recomendado): herramientas completas + capa de compatibilidad. Solo necesita python3 3.9+ en el PATH (sin dependencias de terceros; no instala ni descarga nada al arrancar).
CLI de respaldo: ligera, solo Node. Úsala si no puedes correr el MCP.

Si falta Python, la ruta te da la solución para tu sistema. En Windows el comando debe llamarse python3 (ver Requisitos), y después de instalar Claude Code, Git o Python abres una ventana nueva de PowerShell y reinicias Claude Code: una ventana abierta antes no ve el PATH nuevo.

Paso 2: Versión y edición de Odoo (opcional)¶

Community · Enterprise · Online (odoo.com/SaaS) · No estoy seguro. La capa de compatibilidad cubre las versiones 10-19 automáticamente; este dato es solo contexto.

Paso 3: Datos de conexión¶

Antes de los datos, la ruta te pregunta para qué es la conexión:

Para aprender o practicar: de preferencia el sandbox (Fase 1, opción 2). Con una instancia real, recomienda Read-only mode activo y el Permission profile readonly.
Para trabajo real: el Permission profile standard y Read-only mode activo los primeros días. La escritura se activa solo cuando confirmas que la quieres.
URL de Odoo, p. ej. https://mi-empresa.odoo.com (esquema + host, sin ruta final).
Nombre de la base de datos: Settings → Database, o visible en la URL de login. En Odoo Online (*.odoo.com) suele ser el subdominio (mi-empresa para https://mi-empresa.odoo.com): la ruta lo sugiere y te pide confirmarlo.
Correo de acceso: la cuenta con la que inicias sesión.
Credencial: una API key (Odoo 14+, recomendada) o una contraseña (Odoo < 14). Para la API key: Preferencias → Account Security → New API Key (se muestra una sola vez; cópiala). En Odoo 19+ la API key es la que permite usar JSON-2.

Odoo Online

En Odoo Online la única credencial que funciona es una API key (los usuarios entran por odoo.com, a menudo con 2FA), y solo los planes Custom permiten acceso a la API. Desde Odoo 18 las keys caducan: un usuario que no es administrador obtiene como máximo 1 día, salvo que alguno de sus grupos permita más. Anota la fecha de caducidad; odoo_online_profile la muestra después.

Estos valores se capturan en el diálogo de opciones del plugin, no en el chat.

Seguridad

Nunca pegues el secreto en el chat ni lo escribas en un archivo que el repositorio rastree. Usa un usuario de Odoo de mínimo privilegio para el agente. Ver Seguridad.

Paso 4: Persistir la configuración¶

Para el servidor MCP:

Corre /plugin, abre odoo-tools y elige Configure options (o /plugin configure <id>).
Llena URL, base de datos, login y API key (o contraseña en Odoo < 14). Opcional: Transport preference (auto por defecto: JSON-2 en Odoo 19+ con API key; también json2, jsonrpc o xmlrpc), Request timeout (120 s por defecto), Read-only mode (recomendado los primeros días y en demos), Permission profile (standard por defecto: sin borrados, sin cambios estilo Studio, sin correos de salida salvo notas internas, sin cambios a usuarios ni permisos y sin secretos guardados; también readonly, builder para sandboxes y staging, o full para conservar el comportamiento de la 1.4) y Permission policy file (opcional: la ruta absoluta a reglas por modelo, ver Política de permisos).
Reinicia Claude para que el servidor MCP tome las opciones.

El diálogo de opciones no dice qué copia del plugin edita. Si la revisión de copias del Paso 0 encontró más de una, la ruta corrige eso primero; después de guardar, corre la revisión de opciones sobre esa copia y actúa sobre lo que lista.

En un equipo remoto o sin interfaz, claude plugin configure <id> --values-stdin guarda las opciones sin el diálogo (ver Instalación). Pasa el JSON desde un archivo protegido o tu gestor de secretos; Claude nunca te pide, lee ni repite la key.

La API key y la contraseña son opciones sensitive: se capturan enmascaradas y se guardan en el almacén seguro de credenciales del sistema operativo, no en settings.json ni en tu perfil de shell. No exportes ODOO_* en ~/.bashrc/~/.zshrc ni con setx para el plugin.

Para la CLI, corre /odoo-tools:odoo-setup-cli: instala la CLI y crea un .env local en ~/.claude/tools/odoo-cli, legible solo por tu usuario y con marcadores de posición. Pega tú el secreto en tu propio editor; Claude nunca te lo pide en el chat.

Fase 2: Verificar (definición de terminado)¶

MCP: llama a odoo_version. Su respuesta debe traer plugin y policy: sin policy, respondió una copia anterior a la 1.5.0 (vuelve al Paso 0 y detente); con note, la política está bloqueada (corrige lo que nombra y reconecta). Éxito = devuelve versión + edición + despliegue + transporte, y la copia que respondió (plugin.copy). En Odoo 19+ el transporte debería ser json2; un transport_notice indica que se usan los endpoints obsoletos (normalmente porque no hay API key) y dice cómo corregirlo. Su bloque policy muestra el perfil activo y las herramientas ocultas. Luego prueba: odoo_search_read { "model": "res.partner", "fields": ["name"], "limit": 1 }.
Odoo Online (despliegue saas o una versión saas~, p. ej. saas~19.2): llama también a odoo_online_profile y revisa la serie, cuándo caduca tu API key y los límites del plan.
CLI: node ~/.claude/tools/odoo-cli/dist/cli.js contacts '{"limit":1}'.

Si falla, diagnostica por el error:

odoo_version no existe como herramienta → el servidor MCP no arrancó. Sigue primero el Paso 0b: en Cowork y Claude chat nunca arranca y la solución no es Python. En Claude Code, revisa las opciones, luego python3 --version (3.9+) y reinicia Claude. En Windows, Failed to connect con Connection closed en claude mcp list es la señal de que falta python3; ver Solución de problemas.
odoo_version responde sin bloque policy → respondió una copia anterior a la 1.5.0; ver Dos copias de odoo-tools
error de autenticación → revisa DB / login / API key
error de transporte → revisa la URL (esquema + host)
"database not found" → revisa el nombre exacto de la base
solo aparece odoo_version y su bloque policy trae un error → el perfil o el archivo de política no son válidos y el servidor arrancó bloqueado; ver Solución de problemas

Fase 3: Entrenamiento (15-20 minutos, práctico)¶

La ruta propone ocho ejercicios. Tú escribes la petición con tus palabras y Claude te explica qué herramienta respondió y por qué. Los ejercicios 1-5 son de solo lectura; del 6 al 8 escriben y solo se hacen en el sandbox o en una base de pruebas, pidiendo confirmación antes de cada escritura.

Conoce tu instancia: «¿qué versión y edición de Odoo tengo?» → odoo_version, odoo_module_info.
Busca registros: «muéstrame 5 clientes de México» → odoo_search_read con un dominio.
Entiende un modelo: «¿qué campos tiene una orden de venta?» → odoo_list_models, odoo_fields_get.
Resume: «total facturado por mes este año» → odoo_read_group.
Exporta: «exporta los productos activos a CSV» → /odoo-export.
Escribe con confirmación (sandbox/pruebas): crea un contacto de prueba, cambia su teléfono y luego archívalo → odoo_create, odoo_write (con {"active": false} para archivar). Con el perfil por defecto standard los borrados se rechazan y odoo_unlink no se lista: archivar es el camino reversible. Para practicar un borrado, pon Permission profile en full en el sandbox (nunca en producción) y reconecta (/mcp); entonces odoo_unlink borra el contacto.
Low-code estilo Studio (sandbox/pruebas): un campo o una automatización → Studio-style. Necesita el Permission profile builder (solo sandboxes y staging).
Importación con prueba previa (sandbox/pruebas): «importa estos 3 contactos» → odoo_import_preview (Odoo revisa cada fila y no guarda nada) y, cuando confirmas, odoo_import (todas las filas o ninguna). Una columna id lleva identificadores externos y actualiza los registros que ya los tienen.

Fase 4: Uso diario¶

Necesidad	Usa
Preguntar por tus datos	pregunta directo: el agente `odoo` y las herramientas MCP responden
Chequeo de la conexión y reporte de soporte	`/odoo-doctor`
Exportar registros	`/odoo-export`
Diferencias entre versiones 10-19	`/odoo-tools:odoo-crossversion`
Campos y automatizaciones	`/odoo-tools:odoo-studio-style`
Planear una migración	el agente `odoo-migrator`
Sandbox: estado, detener, arrancar	`/odoo-tools:deploy-local status`
Un equipo sin Python	`/odoo-tools:odoo-setup-cli` (CLI) o `/odoo-tools:deploy-local container`
Odoo Online: serie, caducidad de la API key, límites del plan	`odoo_online_profile`
¿Por qué se rechazó una llamada? ¿Qué puede hacer este usuario?	`odoo_access_check`
Adjuntos de un registro o el PDF guardado de una factura	`odoo_record_documents`
Cargar muchos registros a la vez	`odoo_import_preview` y, tras confirmar, `odoo_import`
Nombres de parámetros de un método (JSON-2, `odoo_execute`)	`odoo_api_catalog`
Qué perfil de permisos está activo y qué herramientas oculta	`/odoo-doctor` o el bloque `policy` de `odoo_version`
Revisar un archivo de política sin conexión	`--check-policy` (ver Política de permisos)

Buenos hábitos: deja el modo solo lectura activo salvo que una tarea necesite escribir, confirma cada escritura y prueba los cambios masivos en el sandbox. Cuando la política de permisos de odoo-tools rechaza una llamada, el rechazo es definitivo: Claude te lo explica junto con la opción que lo cambia, y no busca otro camino (otra herramienta, la CLI de respaldo o la shell). /odoo-doctor muestra el perfil activo.

Fase 5: Despliegue (equipo o producción)¶

La ruta recorre esta lista contigo:

Un usuario de Odoo por persona, de mínimo privilegio y con su propia API key.
Solo lectura por defecto; escritura solo para quien la necesita. Deja el Permission profile en standard (o readonly) en producción, builder solo en sandboxes y staging, y full solo donde decidas conservar todos los derechos del usuario de Odoo. Con un usuario administrador en producción, parte de una copia de ${CLAUDE_PLUGIN_ROOT}/docs/policy-examples/production-hardened.json guardada fuera de todo proyecto (por ejemplo ~/.config/odoo-tools/policy.json, cuya ruta absoluta va en Permission policy file) y revisa la copia antes con python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-policy <archivo>. Ver Ejemplos.
URL HTTPS y transporte auto, salvo que haya una razón.
Piloto primero: repite los flujos clave en el sandbox o en una copia.
Respaldos antes de escrituras masivas o cambios estilo Studio.
Cada equipo instala el plugin una vez, desde el marketplace de Transgenia: dentro de Claude Code, /plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online; o en una terminal, claude plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online --scope user (en Claude Code anterior a 2.1.275, primero agrega el marketplace). Después recorre la ruta, que revisa que solo haya una copia activa; los que no tienen Python usan el modo contenedor.
Actualizaciones desde /plugin, leyendo el CHANGELOG antes de actualizar a usuarios de producción.
Odoo Online: planea la rotación de API keys (caducan desde Odoo 18; odoo_online_profile dice cuándo), dosifica el trabajo masivo (alrededor de 1 llamada por segundo, importaciones de máximo 500 filas por llamada) y espera una nueva línea saas~X.Y cada pocos meses.

Acompañamiento de Transgenia

En los puntos donde más ayuda (configuración bloqueada, fin del entrenamiento, sandbox y despliegue) el plugin te recuerda que Transgenia ofrece mantenimiento, soporte, capacitación y despliegue asistido, solo por sus canales oficiales: dev@transgenia.org · WhatsApp +52 55 8034 0405. Ver Soporte.