Instalación¶

Novedades en v1.6.0

Comandos de instalación por superficie: /plugin install ... dentro de Claude Code, o claude plugin install ... --scope user en una terminal. Un comando /plugin escrito en PowerShell falla. Ver Como plugin de Claude.
Dos copias de odoo-tools: las señales, y las revisiones de copias y de opciones que dejan una sola copia actual. Ver Dos copias de odoo-tools.
odoo_version nombra la copia que responde (bloque plugin). Ver Verificar.
Windows: sin el comando python3, claude mcp list reporta el servidor como Failed to connect con Connection closed. El comando de PowerShell que lo corrige está en Requisitos.
El estado not_started y una sesión local: el estado not_started con el motivo user_config_unsupported es el caso de Cowork y Claude chat, y ninguna actualización lo cambia. Usa una sesión local de la pestaña Code o Claude Code en tu equipo; Claude Code no necesita permisos de administrador. Ver Como plugin de Claude.
Docker: el sandbox de Odoo 14.0 a 19.0 trae una API key para el plugin (ver Despliegue local), y la imagen del modo contenedor es ghcr.io/transgenia/odoo-mcp-tools:1.6.0.

Novedades en v1.5.1

Nuevo hook de inicio de sesión, hooks/session_start.py, en lugar de hooks/check_options.py: no lee ninguna opción del plugin ni credencial. Cuando los últimos 14 días no registran una conexión exitosa a Odoo ni un arranque del servidor con todos los datos de conexión, dice dónde corren las herramientas de Odoo. Ver Verificar.
Diagnóstico local: el servidor escribe metadatos en ${CLAUDE_PLUGIN_DATA}/diagnostics (ODOO_DIAG_DIR), y /odoo-tools:odoo-doctor los convierte en un reporte de soporte. Ver Soporte.
Credenciales: el servidor ya no lee ODOO_HTTP_BEARER; solo lee la API key o la contraseña que le pasan las opciones del plugin.
Docker: el modo contenedor de /odoo-tools:deploy-local marca la carpeta de datos del plugin para que el hook no avise, y su imagen es ghcr.io/transgenia/odoo-mcp-tools:1.5.1.

Novedades en v1.5.0

Permisos seguros por defecto. Para conservar el comportamiento de la 1.4, pon la opción Permission profile en full.

Dos opciones nuevas, ambas con valor por defecto: Permission profile (standard; también readonly, builder o full) y Permission policy file (vacía, o la ruta absoluta a un archivo JSON con reglas por modelo). Ver Política de permisos.
Read-only mode ahora oculta las herramientas de escritura (llamar a una sigue explicando por qué se rechaza).
Registro de auditoría: el servidor escribe una línea por llamada a herramienta en la carpeta de datos del plugin (${CLAUDE_PLUGIN_DATA}/audit), y la conserva 90 días.
Revisión sin conexión de un archivo de política con --check-policy.
Docker: el archivo de entorno puede fijar la política y la carpeta de auditoría; se quitó el camino multi-tenant por cabeceras.
La imagen del modo contenedor es ghcr.io/transgenia/odoo-mcp-tools:1.5.0.

Novedades en v1.4.1

Versión de documentación y diagnóstico: el comportamiento del servidor MCP no cambia.

Instalación en un paso: /plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online (Claude Code 2.1.275 o posterior). En versiones anteriores siguen valiendo los dos comandos de siempre.
Dónde corren las herramientas: las herramientas de Odoo corren en Claude Code; Cowork y Claude chat cargan las skills y los comandos sin las herramientas. Ver Dónde funciona.
Aviso de opciones faltantes al iniciar sesión: un segundo hook SessionStart te dice qué opciones obligatorias (URL, base de datos, login) no tienen valor guardado. Nunca lee la API key ni la contraseña. Ver Seguridad.
Configuración sin diálogo: claude plugin configure (Claude Code 2.1.285 o posterior) para equipos remotos o sin interfaz.
Windows: los hooks de inicio de sesión necesitan Git Bash (ver Requisitos).
La imagen del modo contenedor es ghcr.io/transgenia/odoo-mcp-tools:1.4.1.

Novedades en v1.4.0

28 herramientas: seis nuevas para Odoo Online, útiles en cualquier Odoo 10-19 (odoo_online_profile, odoo_api_catalog, odoo_access_check, odoo_record_documents, odoo_import_preview, odoo_import). Ver Referencia de herramientas.
Transporte JSON-2: en Odoo saas~18.4 / 19.0+ con una API key, el modo auto usa la nueva API JSON-2 de Odoo, porque Odoo 22 y Odoo Online saas~21.1 retiran /xmlrpc y /jsonrpc. Nueva opción json2 en Transport preference. Ver Compatibilidad.
odoo_read_group usa formatted_read_group desde saas~18.4 y conserva su salida clásica.
Sandbox de Odoo Community 10.0 a 19.0 (antes 16.0 a 19.0). Ver Despliegue local.
Corregido: odoo_version ya no reporta éxito con una API key o contraseña equivocada; un HTTP 429 ya no cambia de transporte.

Novedades en v1.3.0

Ruta guiada: /odoo-tools:odoo-setup-mcp te acompaña por configuración, verificación, entrenamiento, uso diario y despliegue. Ver Inicio rápido.
Infraestructura local: /odoo-tools:deploy-local levanta un sandbox de Odoo 16-19 en Docker, o el servidor MCP como contenedor (ghcr.io/transgenia/odoo-mcp-tools) para equipos sin Python. Ver Despliegue local.
Releases y paquetes: cada versión se publica como Release en GitHub (zip del plugin + sdist/wheel) y como imagen en GHCR.
Soporte: los errores de conexión indican cómo repararla y a quién acudir. No tienes que reconfigurar nada al actualizar.

Cambios en v1.2.0

Desde la versión 1.2.0, el servidor MCP ya no usa uv (ni uv run --frozen). El plugin lo lanza con python3 directamente desde el código incluido, sin dependencias de terceros en tiempo de ejecución (solo la biblioteca estándar de Python): al arrancar no instala ni descarga nada, y server/uv.lock se eliminó. No tienes que volver a configurar nada: las opciones del plugin que ya capturaste se conservan; solo necesitas python3 3.9 o superior en el PATH en lugar de uv (ver Requisitos más abajo). Además:

Tiempo de espera: ODOO_TIMEOUT pasa de 30 a 120 s por defecto (el limit_time_real por defecto de Odoo) y ahora es la opción del plugin Request timeout. XML-RPC también lo respeta: antes, un Odoo que no respondía podía bloquear una llamada XML-RPC indefinidamente.
Cargan las 9 skills y comandos. Antes, un skills/SKILL.md en la raíz de skills/ ocultaba 5 de las 6 skills, así que /odoo-tools:odoo-setup-mcp no existía.
Corregido un bloqueo (deadlock) de odoo_version en instancias Community.
Los argumentos de cada herramienta se validan contra su esquema: si no coinciden, la llamada se rechaza con Input validation error: ... antes de llegar a Odoo.
En modo auto, una escritura nunca se repite por XML-RPC tras agotarse el tiempo de espera o un HTTP 5xx: el error indica que la llamada "may or may not have been applied" (puede o no haberse aplicado). Ver Solución de problemas.

Cambios en v1.1.0 / migración

Desde la versión 1.1.0, el plugin se configura con opciones del plugin (userConfig) y ya no lee variables de entorno ODOO_* de tu shell. Si en la v1.0.0 exportaste ODOO_* en ~/.bashrc, ~/.zshrc o con setx, captura esos valores una vez en /plugin → odoo-tools → Configure options (y luego puedes quitarlos de tu perfil de shell). El servidor standalone (Docker, python -m odoo_mcp) sigue leyendo las variables ODOO_*.

Como plugin de Claude (recomendado)¶

Instálalo una vez, desde el marketplace de Transgenia, de una de estas dos formas.

Dentro de Claude Code (escrito en una sesión):

/plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online
/odoo-tools:odoo-setup-mcp

En una terminal (PowerShell, Terminal o bash), para todas tus carpetas:

claude plugin install odoo-tools --marketplace Transgenia/MCP-Odoo-Tools-CE-EE-and-online --scope user

y luego abre Claude Code y escribe /odoo-tools:odoo-setup-mcp. Un comando /plugin va dentro de Claude Code, nunca en la terminal: escrito en PowerShell, falla con un error de comando no reconocido (not recognized). Un comando claude plugin va en la terminal, nunca en el chat. En Windows, si claude no se reconoce justo después de instalar Claude Code, abre una ventana nueva de PowerShell (ver Requisitos).

La primera forma agrega el marketplace e instala el plugin en un solo paso (Claude Code 2.1.275 o posterior). En un Claude Code anterior, que no tiene la opción --marketplace, agrega primero el marketplace, dentro de Claude Code:

/plugin marketplace add Transgenia/MCP-Odoo-Tools-CE-EE-and-online
/plugin install odoo-tools

Claude Code no necesita permisos de administrador: su instalador nativo lo deja en tu carpeta personal (~/.local/bin/claude en macOS y Linux), y en Windows la guía de Anthropic dice que no hace falta correrlo como administrador. En un plan Team o Enterprise, tu organización decide qué plugins recibes y si la pestaña Code de Claude Desktop ofrece sesiones locales.

El directorio de plugins de Claude publica una versión solo después de que Anthropic la revisa, así que puede ofrecer un odoo-tools más antiguo que el marketplace de Transgenia (por ejemplo la 1.4.0, anterior a la política de permisos de la 1.5.0), y buscar actualizaciones en las apps de Claude no encuentra una versión más nueva hasta entonces. En Cowork y Claude chat ninguna versión corre las herramientas de Odoo, así que una actualización no cambia eso ahí. Instala una sola copia: la ruta guiada lo revisa (ver Dos copias de odoo-tools).

Claude Code te pide los datos de conexión al habilitar el plugin. Para cambiarlos después: /plugin → odoo-tools → Configure options, o /plugin configure <id> dentro de una sesión (en VS Code, el engrane en la fila del plugin). El diálogo de opciones no dice qué copia del plugin edita.

Las opciones del plugin existen solo en Claude Code

Cowork no pide opciones de plugin e ignora el servidor MCP de este plugin, porque sus opciones de conexión no tienen valor por defecto, y Claude chat ignora el servidor MCP local de un plugin. Por eso las herramientas de Odoo no están disponibles en ninguno de los dos (las skills y los comandos sí cargan). Claude Desktop nombra ese caso, para el servidor de este plugin, con el estado not_started y el motivo user_config_unsupported; ninguna actualización del plugin lo cambia. Una sesión en la nube de Claude Code es otro caso: tiene el plugin sincronizado, pero no sus opciones, que se quedan en el equipo donde las capturaste, así que usa una sesión local. En claude.ai en la web, el menú de tres puntos del plugin ofrece acciones como quitarlo, editarlo con Claude o duplicarlo, y ningún lugar para las opciones de conexión. Ver Dónde funciona y Solución de problemas.

Sin diálogo interactivo (`claude plugin configure`)¶

En scripts o en equipos remotos o sin interfaz (Claude Code 2.1.285 o posterior):

claude plugin configure <id> --json lista las opciones sin valor guardado. En una configuración que funciona siguen en esa lista la credencial que no usas (API key o contraseña) y las opciones que tienen valor por defecto; solo odoo_url, odoo_db, odoo_login y una credencial deben tener valor.
claude plugin configure <id> --values-stdin guarda valores leídos de la entrada estándar como un objeto JSON de cadenas de una sola línea. Reinicia Claude Code después.

<id> es el identificador completo nombre@marketplace que muestra claude plugin list (por ejemplo odoo-tools@synced para un plugin sincronizado desde tu cuenta de Claude). Pasa el JSON desde un archivo protegido o tu gestor de secretos; nunca escribas la key en la línea de comandos ni en el chat.

La entrada mcpServers del plugin lanza el servidor con:

python3 ${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py

run_stdio.py pone primero en sys.path el código incluido en server/src (así ningún otro paquete odoo_mcp instalado en tu equipo puede sustituirlo) y arranca el servidor MCP por stdio. El servidor usa solo la biblioteca estándar de Python (el protocolo MCP y los transportes JSON-2, JSON-RPC y XML-RPC están implementados sobre ella), así que no instala ni descarga nada al arrancar: el código que corre es exactamente el código legible que viene en la carpeta del plugin. No se necesita publicación en PyPI, ni uv, ni un entorno virtual.

Opciones del plugin¶

Opción	Requerida	Notas
Odoo URL	sí	esquema + host, p. ej. `https://mi-empresa.odoo.com` (sin ruta final)
Odoo database	sí	nombre de la base de datos
Odoo login	sí	login (normalmente un correo) del usuario de Odoo; de preferencia de mínimo privilegio
Odoo API key	sí*	Odoo ≥ 14: Preferencias → Account Security → New API Key. Odoo 19+ la necesita para JSON-2, la única API que queda en Odoo 22. Opción `sensitive`
Odoo password (Odoo < 14 only)	sí*	solo Odoo 10-13 (sin API keys). Opción `sensitive`
Transport preference	no	`auto` (default) / `json2` / `jsonrpc` / `xmlrpc`. `auto` usa JSON-2 en Odoo saas~18.4 / 19.0+ cuando hay API key, y JSON-RPC y luego XML-RPC en los demás casos
Request timeout	no	número, segundos máximos por llamada a Odoo (default: 120, el `limit_time_real` por defecto de Odoo; mín. 5, máx. 3600); equivale a `ODOO_TIMEOUT`
Read-only mode	no	booleano (default: apagado); las herramientas de escritura, borrado, importación y Studio no se listan, y llamar a una se rechaza antes de que nada llegue a Odoo (equivale a `ODOO_READONLY`)
Permission profile	no	`standard` (default), `readonly`, `builder` o `full`: qué pueden hacer las herramientas de Odoo encima de los derechos del usuario de Odoo. `full` conserva el comportamiento de la 1.4. Ver Política de permisos (equivale a `ODOO_POLICY`)
Permission policy file	no	vacía (default), o la ruta absoluta a un archivo JSON con reglas por modelo encima del perfil, p. ej. `~/.config/odoo-tools/policy.json`. Mantenlo fuera de tus proyectos. Se lee una vez al arrancar el servidor (equivale a `ODOO_POLICY_FILE`)

* llena una de las dos: API key (Odoo ≥ 14) o contraseña (Odoo < 14).

La entrada mcpServers del plugin fija además ODOO_AUDIT_DIR en ${CLAUDE_PLUGIN_DATA}/audit y ODOO_AUDIT_RETENTION_DAYS en 90: el servidor escribe una línea de auditoría por llamada a herramienta, con nombres y conteos, nunca valores ni secretos (ver Registro de auditoría). Desde la v1.5.1 fija también ODOO_DIAG_DIR en ${CLAUDE_PLUGIN_DATA}/diagnostics: el diagnóstico local del servidor, solo metadatos (ver Almacenamiento local).

El perfil por defecto es standard

Con standard no se listan odoo_unlink, odoo_add_field ni odoo_add_automation, y se rechazan, entre otras cosas, los correos de salida (salvo notas internas) y los cambios a usuarios, permisos, módulos y ajustes. Si tu flujo necesita todo lo que permite el usuario de Odoo, elige full; para campos, vistas y automatizaciones en un sandbox, builder. Un cambio de perfil necesita reconectar el servidor (/mcp).

Las opciones sensitive (API key y contraseña) se capturan enmascaradas y se guardan en el almacén seguro de credenciales del sistema operativo, nunca en settings.json ni en tu perfil de shell. No hace falta (ni se recomienda) exportar ODOO_* en ~/.bashrc, ~/.zshrc o con setx para el plugin.

Dos copias de odoo-tools¶

Claude Code puede correr a la vez dos copias con el mismo nombre, por ejemplo una del directorio de plugins de Claude en una carpeta de proyecto y otra del marketplace de Transgenia para tu usuario. Entonces las opciones que guardas pueden ir a una copia mientras responden las herramientas de la otra. Las señales:

Configure options no muestra Permission profile (una copia anterior a la 1.5.0);
odoo_version responde sin un bloque policy;
la pestaña Errors del plugin dice Plugin option "odoo_url" isn't set para una copia que nunca configuraste. Ese mensaje es de Claude Code: la copia que nombra (la muestra claude plugin list) no tiene opciones guardadas.

Desde la v1.6.0, odoo_version nombra la copia que responde (plugin.copy, ver Verificar), y la ruta guiada se detiene ante una copia anterior a la 1.5.0, antes de cualquier escritura.

La revisión de copias y la revisión de opciones¶

Dentro de Claude Code, la ruta guiada (/odoo-tools:odoo-setup-mcp) y /odoo-tools:odoo-doctor corren la revisión de copias y, para la copia que conserva, la revisión de opciones. Son estos comandos de shell, que Claude corre por ti en Claude Code:

claude plugin list --json | python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-copies
claude plugin configure <id> --json | python3 "${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py" --check-options

${CLAUDE_PLUGIN_ROOT} es la carpeta del plugin, y <id> la copia que conservar, como odoo-tools@transgenia-odoo-tools. Cada revisión lee en su entrada estándar el JSON que imprime un comando de Claude Code: no corre ningún programa, no contacta nada y nunca imprime un valor sensible, contenga lo que contenga la entrada. Las dos leen UTF-8, también desde una tubería de Windows. Sale con 0 si no hay nada que corregir, con 1 si hay algo y con 2 si la entrada no es ese JSON; --json imprime el reporte como JSON. La revisión de opciones necesita Claude Code 2.1.285 o posterior. Si claude no se encuentra, su ruta completa es "$HOME/.local/bin/claude".

Así se ve la revisión de copias con una copia antigua del directorio en una carpeta de proyecto y una actual del marketplace de Transgenia:

odoo-tools copies Claude Code knows in this folder:
  active       odoo-tools@anthropic-plugin-directory 1.4.0 (project, ~/projects/odoo)
  active       odoo-tools@transgenia-odoo-tools 1.6.0 (user)
  not loaded   odoo-tools@synced unknown (synced from claude.ai): a copy on this computer has the same name and takes precedence
To fix:
  - 2 copies are active at once, so Claude Code may use the tools of one and the options of another. Keep one: odoo-tools@transgenia-odoo-tools 1.6.0 (user).
  - odoo-tools@anthropic-plugin-directory 1.4.0 (project, ~/projects/odoo) is older than 1.5.0: it has no permission policy, profile or audit log.
In a terminal (PowerShell, Terminal or bash), not inside Claude Code:
  cd ~/projects/odoo
  claude plugin uninstall odoo-tools@anthropic-plugin-directory --scope project
Then restart Claude Code, or run /reload-plugins inside it.
Result: 2 to fix

Cómo leerla:

Cada copia lleva su estado, su id, su versión y su alcance: active (cargada en esta carpeta), not loaded (una copia de claude.ai detrás de una copia local con el mismo nombre, que tiene prioridad), other folder (una instalación de otra carpeta, con la nota installed for that folder only) o disabled. Un mismo id instalado en dos alcances es una sola copia, y una instalación de proyecto o local cuenta solo en su propia carpeta: su carpeta de proyecto o una carpeta dentro de ella.
To fix dice qué corregir: dos copias activas a la vez, o una copia anterior a la 1.5.0, sin política de permisos, perfil ni registro de auditoría. Nombra la copia que conservar y prefiere, en este orden, una con la política de permisos, la del marketplace de Transgenia, la más nueva y la de tu usuario.
In a terminal da los comandos exactos que quitan las demás: un cd a la carpeta del proyecto, entre comillas cuando bash o PowerShell lo necesitan (una ruta de Windows se escribe con /), y luego claude plugin uninstall <id> --scope <alcance> (para una copia de tu usuario, solo --scope user, sin cd). Si el nombre de la carpeta contiene ", $, `, !, [ o ] (comodines para el cd de PowerShell), o si es una ruta de red (con \), en lugar del cd va una línea de comentario, # first change to this folder by hand: ...: cambia tú a esa carpeta. Córrelos en PowerShell, Terminal o bash, nunca como comandos /plugin, y reinicia Claude Code o corre /reload-plugins dentro de él.
Una copia que se administra en claude.ai no se quita desde la terminal: la línea Note: dice que la quites ahí (Customize, Plugins). Si todas las copias activas son anteriores a la 1.5.0, da además los comandos que dejan una copia actual. Para una copia antigua del marketplace de Transgenia son claude plugin marketplace update transgenia-odoo-tools y luego claude plugin update odoo-tools@transgenia-odoo-tools --scope <alcance>, con un cd a la carpeta del proyecto antes si es de proyecto o local. Desinstalarla e instalarla otra vez puede reutilizar una copia local desactualizada del marketplace y volver a dejar la misma versión antigua. Los comandos de actualización sirven siempre. Para una copia de otro marketplace, los comandos que la quitan y luego el que instala la del marketplace de Transgenia. Si no hay ninguna activa, da el comando que la instala. Antes de una instalación, si el marketplace de Transgenia ya es conocido, lo actualiza primero.
Result: ok, o cuántas cosas hay que corregir.

La revisión de opciones lista la URL de Odoo, la base de datos, el login, qué credencial está puesta (API key, password o none, nunca su valor), Read-only mode y, en una copia con la política de permisos, el perfil y el archivo de política. De la URL solo muestra el esquema, el host y el puerto: nunca repite el usuario, la contraseña, una ruta, una consulta ni un fragmento, que pueden llevar una contraseña o el token de un enlace de portal copiado. Si la URL lleva una @, o si no puede leer un host, dice que la URL está puesta y no muestra ninguna parte de ella: una contraseña con # o ? cambiaría dónde se corta la URL. En To fix señala una copia sin la opción Permission profile (anterior a la 1.5.0: corre la revisión de copias), las opciones obligatorias que faltan, la falta de credencial, una URL con cualquier @ (la rechaza como usuario o contraseña) y una URL que no es solo esquema y host. En Note: avisa de una API key y una contraseña puestas a la vez (se usa la API key), de la / final de la URL (se ignora), de http sin cifrar hacia otro equipo y de un tiempo de espera menor a 30 s. Las opciones que faltan se capturan en el diálogo que abres dentro de Claude Code con /plugin configure <id>, nunca en el chat.

Quitar una copia desde la terminal¶

Sin Claude, en una terminal y desde la carpeta del proyecto, claude plugin list muestra cada copia con su versión y su alcance; conserva un odoo-tools@... y quita los demás ahí:

claude plugin list
claude plugin uninstall odoo-tools@anthropic-plugin-directory --scope project

Usa el id y el alcance que muestra claude plugin list (--scope user para una copia instalada para tu usuario) y reinicia Claude Code. La copia del directorio es odoo-tools@anthropic-plugin-directory; no existe odoo-tools@claude-plugins-official.

Si la copia que conservas es una copia antigua del marketplace de Transgenia (anterior a la 1.5.0), no la desinstales para instalarla otra vez: la instalación puede reutilizar una copia local desactualizada del marketplace y volver a dejar la misma versión antigua. Los comandos de actualización sirven siempre: actualiza el marketplace y luego la copia, con el alcance que muestra claude plugin list (para una copia de proyecto o local, desde la carpeta del proyecto):

claude plugin marketplace update transgenia-odoo-tools
claude plugin update odoo-tools@transgenia-odoo-tools --scope user

Ejecutar el servidor MCP directamente (standalone)¶

# desde un checkout, con python3 3.9+ (sin instalar nada)
python3 server/run_stdio.py

# o instalado como paquete (se recomienda un entorno virtual); expone el comando odoo-mcp
pip install ./server && odoo-mcp

Requisitos¶

Servidor MCP: python3 3.9 o superior en el PATH. Nada más: cero dependencias de terceros en tiempo de ejecución. Compruébalo con python3 --version.
- macOS: python3 viene con las Command Line Tools de Apple (xcode-select --install). Si tu Mac pide un administrador para instalarlas y no lo eres, tu equipo de TI las instala, o pide a Transgenia una configuración asistida.
- Linux: las distribuciones incluyen python3 (si falta, instálalo con tu gestor de paquetes, p. ej. sudo apt install python3).
- Windows: el comando debe llamarse python3. El Python de Microsoft Store incluye python3.exe; los instaladores de python.org solo crean python.exe/py.exe: instala el Python de Microsoft Store o pon un python3.exe en el PATH (una copia o enlace duro de python.exe en la misma carpeta; el comando de PowerShell está abajo). Un alias de PowerShell o doskey no basta, porque Claude Code lanza el comando directamente. Sin python3, claude mcp list reporta el servidor del plugin como Failed to connect con Connection closed, y nada menciona a Python. Ver Solución de problemas.
- Windows, hooks de inicio de sesión: son comandos de shell, así que necesitan Git for Windows (Git Bash). Sin él, Claude Code los corre en PowerShell, donde fallan con un error de hook SessionStart. Si Git Bash está instalado pero Claude Code no lo encuentra, define CLAUDE_CODE_GIT_BASH_PATH. El servidor MCP no se ve afectado.
- Windows, después de instalar Claude Code, Git o Python: abre una ventana nueva de PowerShell y reinicia Claude Code; una ventana abierta antes de la instalación no ve el PATH nuevo (claude no se reconoce, o where.exe git no encuentra nada). El instalador nativo de Claude Code deja claude.exe en %USERPROFILE%\.local\bin.
CLI de respaldo (opcional): Node.js 18+.

Windows: un python3.exe junto a python.exe

El enlace duro, en PowerShell:

$python = (Get-Command python -ErrorAction Stop).Source
New-Item -ItemType HardLink -Path (Join-Path (Split-Path $python) "python3.exe") -Target $python

Necesita permiso de escritura en la carpeta de Python: para una instalación en C:\Program Files, abre PowerShell como administrador. Si Get-Command python no encuentra nada, o encuentra un archivo dentro de WindowsApps, Python no está en el PATH: vuelve a correr el instalador de python.org y marca "Add python.exe to PATH", o instala el Python de Microsoft Store. La CI comprueba esta solución en Windows (windows-launch.yml).

Extras opcionales¶

pip install -e "./server[cache]"    # caché de esquema con TTL (cachetools)
pip install -e "./server[metrics]"  # métricas Prometheus en /metrics
pip install -e "./server[otel]"     # trazas OpenTelemetry (OTLP)

Los extras nunca bloquean el arranque: si no están instalados, esas capacidades simplemente quedan inactivas (degradación elegante; la caché de esquema usa entonces una implementación de la biblioteca estándar). El plugin no instala ningún extra.

Configuración standalone (variables de entorno)¶

Solo aplica cuando corres el servidor fuera del plugin (Docker, python -m odoo_mcp, python3 server/run_stdio.py desde un checkout). Dentro del plugin, estos valores se llenan desde las opciones del plugin.

Variable	Requerida	Notas
`ODOO_URL`	sí	`https://host` (sin ruta final)
`ODOO_DB`	sí	nombre de la base de datos
`ODOO_LOGIN`	sí	correo de acceso
`ODOO_API_KEY`	sí*	Odoo ≥ 14; se crea en Account Security. Es la única credencial que acepta JSON-2
`ODOO_PASSWORD`	sí*	úsala en Odoo < 14 (sin API keys)
`ODOO_TRANSPORT_PREF`	no	`auto` (default) / `json2` / `jsonrpc` / `xmlrpc` (ver Compatibilidad)
`ODOO_READONLY`	no	`1` lista y corre solo las herramientas de lectura (opción Read-only mode)
`ODOO_POLICY`	no	perfil de permisos: `readonly`, `standard` (default), `builder` o `full` (opción Permission profile, ver Política de permisos)
`ODOO_POLICY_FILE`	no	ruta absoluta a un archivo de política opcional (opción Permission policy file)
`ODOO_AUDIT_DIR`	no	carpeta de auditoría; `stderr` (el default fuera del plugin) u `off`
`ODOO_AUDIT_RETENTION_DAYS`	no	días que se conserva un archivo de auditoría (default 90; `0` los conserva)
`ODOO_DIAG_DIR`	no	carpeta del diagnóstico local (`server.jsonl`, solo metadatos); sin valor u `off` no escribe nada. El plugin pasa `${CLAUDE_PLUGIN_DATA}/diagnostics`
`ODOO_TIMEOUT`, `ODOO_CACHE_TTL`	no	enteros (segundos); `ODOO_TIMEOUT` (120 por defecto) aplica a JSON-RPC y, desde v1.2.0, también a XML-RPC
`ODOO_METRICS`, `ODOO_OTEL_ENDPOINT`	no	observabilidad opcional

* debes definir una de ODOO_API_KEY o ODOO_PASSWORD.

El servidor MCP no persiste credenciales en disco; sus líneas de auditoría solo guardan nombres, conteos y tiempos, y su diagnóstico local solo metadatos. Transgenia no recibe tus credenciales ni tus datos; los resultados de las herramientas sí regresan a tu cliente MCP y a tu proveedor de modelo, como con cualquier herramienta. Ver Privacidad.

Revisa un archivo de política antes de configurarlo (sin conexión, no se envía nada a Odoo):

python3 server/run_stdio.py --check-policy ~/.config/odoo-tools/policy.json --explain res.users:write

Ver --check-policy.

El reporte de soporte también se genera sin conexión: python3 server/run_stdio.py --diagnose lee el diagnóstico local (ODOO_DIAG_DIR) y la auditoría (ODOO_AUDIT_DIR), o las carpetas que le pases con --diag-dir y --audit-dir, y nunca contacta a Odoo. Ver Soporte.

CLI de respaldo (opcional)¶

/odoo-tools:odoo-setup-cli

Requiere Node.js 18+. Instala la CLI en ~/.claude/tools/odoo-cli y crea ahí un .env local, legible solo por tu usuario, con marcadores de posición: tú pegas el secreto (API key o contraseña) en tu propio editor; Claude nunca te lo pide en el chat. Ver la página CLI de respaldo para el detalle de comandos.

Docker (opcional)¶

El directorio docker/ del repositorio construye una imagen que corre el mismo servidor stdio. Conéctate con docker run -i --rm --env-file ./odoo.env odoo-mcp-tools, donde odoo.env es un archivo que creas tú con las variables ODOO_* (permisos 600, fuera del control de versiones). Ese archivo puede fijar también la política de permisos y la carpeta de auditoría; monta el archivo de política en solo lectura y la carpeta de auditoría con escritura para el usuario del contenedor (mcp):

# en odoo.env
# ODOO_POLICY=standard
# ODOO_POLICY_FILE=/policy/policy.json
# ODOO_AUDIT_DIR=/audit

docker run -i --rm --env-file ./odoo.env \
  -v ~/.config/odoo-tools/policy.json:/policy/policy.json:ro \
  -v ~/.odoo-tools/audit:/audit ghcr.io/transgenia/odoo-mcp-tools:1.6.0

Sin carpeta de auditoría, las líneas van a docker logs. Desde la v1.5.0 el servidor nunca toma una URL ni un secreto de Odoo de una petición del cliente: se quitó el camino multi-tenant por cabeceras (X-Odoo-Url/Db/Login + Bearer), y ODOO_MULTITENANT se lee pero queda reservada, sin efecto. Desde la v1.5.1 el servidor no lee ninguna otra credencial: ODOO_HTTP_BEARER, que leía pero nunca usaba, ya no se lee. Sin ODOO_DIAG_DIR, el contenedor no escribe diagnóstico local. Un modo HTTP remoto, donde el servidor guarde la credencial de Odoo y los clientes se autentiquen ante él, está en la hoja de ruta y necesita su propio diseño.

Verificar¶

Llama a la herramienta odoo_version (o corre /odoo-tools:odoo-doctor). Una respuesta exitosa que reporte versión, edición, despliegue y transporte confirma la instalación de extremo a extremo (desde la v1.4.0, odoo_version inicia sesión primero, así que una credencial equivocada ya no pasa como conexión correcta). Ver Conexión y descubrimiento.

Si al iniciar sesión ves un aviso que empieza con odoo-tools: In Cowork and Claude chat this plugin's Odoo tools do not run, el diagnóstico local no registra en los últimos 14 días una conexión exitosa a Odoo ni un arranque del servidor con todos los datos de conexión. En Claude Code, captura las opciones en Configure options y reinicia; en Cowork o Claude chat, abre una sesión local de la pestaña Code de Claude Desktop. Ver Solución de problemas.

Desde la v1.5.0, la respuesta de odoo_version incluye un bloque policy con el perfil activo, el digest y las herramientas ocultas. Si al iniciar sesión el plugin te avisa que la política bloqueó las herramientas en el último arranque del servidor (the permission policy locked the Odoo tools), pide a Claude que llame a odoo_version para ver el motivo, corrige la opción o el archivo y reconecta el servidor con /mcp. Ver Solución de problemas.

Desde la v1.6.0 la respuesta trae también un bloque plugin: la versión de odoo-tools que respondió y, en Claude Code, su copia instalada (plugin@marketplace, por ejemplo odoo-tools@transgenia-odoo-tools), también con la política bloqueada. Una respuesta sin bloque policy viene de una copia anterior a la 1.5.0: la ruta guiada y /odoo-tools:odoo-doctor se detienen ahí. Ver Dos copias de odoo-tools.