Odoo MCP

Odoo MCP convierte una base de datos de Odoo en un servidor del Protocolo de Contexto de Modelo (MCP). Está diseñado para agentes locales, IDEs y herramientas de automatización que necesitan contexto real de Odoo sin scripts manuales ni acceso de escritura directo inseguro.

Utiliza XML-RPC para Odoo 16-18 y External JSON-2 para Odoo 19. Expone una superficie MCP compacta con herramientas de lectura, diagnósticos, descubrimiento de esquemas, asistentes de migración, escaneo de módulos locales y un flujo de trabajo de escritura controlado.

Aspectos destacados

Capacidad	Lo que te ofrece
22 herramientas MCP	Leer registros, inspeccionar esquemas, construir dominios, escanear módulos, diagnosticar llamadas, reglas de acceso y validar escrituras.
5 prompts de agente	Flujos de trabajo reutilizables para llamadas fallidas, talleres de ajuste/brecha (fit/gap), migración JSON-2, escrituras seguras y auditorías de módulos.
Cobertura Odoo 16-19	XML-RPC por defecto, JSON-2 opcional para Odoo 19.
HTTP transmitible	Soporte local HTTP/SSE para clientes que no usan stdio.
Escrituras seguras	Las operaciones directas `create`, `write` y `unlink` están bloqueadas; las escrituras aprobadas requieren metadatos en vivo, un token de la misma sesión, confirmación explícita y una puerta de entorno.
Pruebas de humo reales	La validación con Docker Compose inicia pilas desechables de Odoo 16.0, 17.0, 18.0 y 19.0, incluyendo usuarios restringidos, reglas de registro personalizadas e instalación/actualización de módulos empaquetados.

Related MCP server: Odoo MCP Server

Instalación

pip install odoo-mcp

Para desarrollo local:

git clone https://github.com/tuanle96/mcp-odoo.git
cd mcp-odoo
uv sync --extra dev

Configuración

Establece los valores de conexión en el entorno:

export ODOO_URL="https://your-odoo-instance.com"
export ODOO_DB="your-database"
export ODOO_USERNAME="your-user"
export ODOO_PASSWORD="your-password-or-api-key"
export ODOO_TRANSPORT="xmlrpc"

Para Odoo 19 JSON-2:

export ODOO_TRANSPORT="json2"
export ODOO_API_KEY="your-odoo-api-key"
export ODOO_JSON2_DATABASE_HEADER="1"

ODOO_JSON2_DATABASE_HEADER=1 envía X-Odoo-Database en llamadas JSON-2. Establécelo en 0 solo cuando el enrutamiento del host o dbfilter ya seleccione la base de datos deseada.

También puedes usar odoo_config.json:

{
  "url": "https://your-odoo-instance.com",
  "db": "your-database",
  "username": "your-user",
  "password": "your-password-or-api-key"
}

Ejecución

Inicia el servidor MCP a través de stdio:

odoo-mcp

python -m odoo_mcp

Inicia HTTP transmitible para clientes locales:

odoo-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

Las conexiones HTTP no locales son rechazadas a menos que pases --allow-remote-http o establezcas MCP_ALLOW_REMOTE_HTTP=1. Este servidor no incluye autenticación HTTP integrada. Coloca los despliegues HTTP remotos detrás de tu propia autenticación, TLS y política de red.

Comprueba el estado del tiempo de ejecución sin iniciar el bucle del servidor:

odoo-mcp --health

Herramientas MCP

Herramienta	Propósito
`execute_method`	Ejecuta un método de modelo revisado. Las operaciones directas `create`, `write` y `unlink` están bloqueadas. Los métodos con efectos secundarios requieren una lista de permitidos exacta o `ODOO_MCP_ALLOW_UNKNOWN_METHODS=1`.
`list_models`	Lista los nombres técnicos y etiquetas de los modelos de Odoo.
`get_model_fields`	Lee metadatos de campo para un modelo.
`search_records`	Ejecuta `search_read` de solo lectura acotado.
`read_record`	Lee un registro por modelo e ID.
`search_employee`	Busca empleados por nombre.
`search_holidays`	Busca registros de vacaciones por rango de fechas.
`diagnose_odoo_call`	Diagnostica una llamada de modelo sin ejecutarla.
`diagnose_access`	Diagnostica la visibilidad de ACL y reglas de registro para la credencial de Odoo actual.
`inspect_model_relationships`	Agrupa campos de relación, campos obligatorios y sugerencias de creación/escritura.
`generate_json2_payload`	Convierte una entrada con formato XML-RPC en un endpoint, cabeceras y cuerpo con nombre para JSON-2.
`upgrade_risk_report`	Muestra riesgos de transporte, método y migración entre versiones de Odoo.
`fit_gap_report`	Clasifica los requisitos en estándar, configuración, Studio, módulo personalizado, evitar o desconocido.
`get_odoo_profile`	Lee la versión del servidor, contexto de usuario, transporte, base de datos y resumen de módulos instalados.
`schema_catalog`	Construye un catálogo de modelos acotado con metadatos de campo opcionales.
`preview_write`	Produce un payload de aprobación no ejecutable para `create`, `write` o `unlink`.
`validate_write`	Valida un payload de escritura contra metadatos `fields_get` en vivo y de confianza.
`execute_approved_write`	Ejecuta solo una escritura confirmada, validada en vivo y en la misma sesión cuando `ODOO_MCP_ENABLE_WRITES=1`.
`scan_addons_source`	Escanea la fuente de módulos locales sin importar el código del módulo.
`build_domain`	Construye y valida un dominio de Odoo a partir de condiciones estructuradas.
`business_pack_report`	Informa sobre módulos, modelos y llamadas de descubrimiento esperados para ventas, CRM, inventario, contabilidad o RRHH.
`health_check`	Informa sobre el estado del tiempo de ejecución de MCP sin datos secretos.

Recursos

URI	Descripción
`odoo://models`	Lista los modelos disponibles.
`odoo://model/{model_name}`	Lee metadatos y campos del modelo.
`odoo://record/{model_name}/{record_id}`	Lee un registro.
`odoo://search/{model_name}/{domain}`	Busca registros con un dominio acotado.

Prompts

Prompt	Úsalo para
`diagnose_failed_odoo_call`	Determinar la causa raíz de una llamada fallida a Odoo antes de reintentar.
`fit_gap_workshop`	Convertir requisitos brutos en categorías de ajuste/brecha de Odoo.
`json2_migration_plan`	Planificar la migración de XML-RPC o JSON-RPC a External JSON-2.
`safe_write_review`	Revisar una propuesta de `create`, `write` o `unlink`.
`custom_module_audit`	Auditar la fuente de módulos locales con escaneo, riesgos y evidencia de negocio.

Modelo de escritura segura

Las escrituras son intencionalmente aburridas.

preview_write crea un payload canónico no ejecutable.
validate_write verifica metadatos del modelo, campos obligatorios, campos de solo lectura, sugerencias de relación, IDs de registro y la forma del payload.
execute_approved_write se ejecuta solo cuando todas las puertas pasan:
- la aprobación provino de validate_write en el mismo proceso del servidor,
- la validación utilizó metadatos fields_get de Odoo en vivo, confiables y no vacíos,
- el token no ha expirado ni ha sido consumido,
- se pasa confirm=true,
- ODOO_MCP_ENABLE_WRITES=1 está establecido.

Las reglas de acceso de Odoo, las reglas de registro y las restricciones del lado del servidor siguen decidiendo el resultado final.

Los métodos con efectos secundarios revisados, como sale.order.action_confirm, pueden habilitarse uno por uno:

export ODOO_MCP_ALLOWED_SIDE_EFFECT_METHODS="sale.order.action_confirm,res.partner.message_post"

ODOO_MCP_ALLOW_UNKNOWN_METHODS=1 sigue siendo compatible para despliegues de confianza, pero health_check lo reporta como modo amplio. Prefiere entradas de lista de permitidos exactas cuando solo necesites un pequeño número de métodos revisados.

Configuración del cliente

Claude Desktop en macOS lee la configuración de MCP desde:

~/Library/Application Support/Claude/claude_desktop_config.json

Usa una ruta absoluta de Python porque las aplicaciones GUI pueden no heredar tu PATH del shell:

{
  "mcpServers": {
    "odoo": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["-m", "odoo_mcp"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_DB": "your-database",
        "ODOO_USERNAME": "your-user",
        "ODOO_PASSWORD": "your-password-or-api-key",
        "ODOO_TRANSPORT": "xmlrpc"
      }
    }
  }
}

Más ejemplos están en docs/client-configs.md.

Docker

Construye la imagen:

docker build -t mcp/odoo:latest -f Dockerfile .

Ejecuta a través de stdio desde un cliente MCP:

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "ODOO_URL",
        "-e", "ODOO_DB",
        "-e", "ODOO_USERNAME",
        "-e", "ODOO_PASSWORD",
        "-e", "ODOO_TRANSPORT",
        "-e", "ODOO_API_KEY",
        "mcp/odoo:latest"
      ]
    }
  }
}

Ejecuta HTTP transmitible localmente:

docker run --rm \
  -p 127.0.0.1:8000:8000 \
  -e ODOO_URL \
  -e ODOO_DB \
  -e ODOO_USERNAME \
  -e ODOO_PASSWORD \
  -e ODOO_TRANSPORT \
  -e ODOO_API_KEY \
  mcp/odoo:latest \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --allow-remote-http

Pruebas

Ejecuta las puertas de calidad normales:

uv run python -m ruff check .
uv run python -m mypy src
uv run python -m pytest

Ejecuta pruebas de humo reales de Odoo:

uv run --python 3.12 --with-editable . scripts/odoo_compose_smoke.py \
  --versions 16.0 17.0 18.0 19.0 \
  --timeout 360 \
  --inspector-smoke

El arnés de humo inicia pilas desechables de Docker Compose, valida el acceso directo a Odoo, valida stdio de MCP y, para Odoo 19, también valida JSON-2 y HTTP transmitible.

Compatibilidad

XML-RPC sigue siendo el transporte predeterminado para una amplia compatibilidad. Odoo 19 admite External JSON-2 a través de ODOO_TRANSPORT=json2. Odoo ha documentado la obsolescencia de XML-RPC y JSON-RPC para Odoo 20, por lo que las nuevas integraciones deben planificar para JSON-2.

Contribución

Los problemas, solicitudes de extracción (pull requests) e informes de compatibilidad son bienvenidos. Comienza con CONTRIBUTING.md, incluye tu versión de Odoo, transporte, tipo de cliente y la verificación que realizaste.

Seguridad

No publiques registros que contengan credenciales de Odoo, claves API, nombres de bases de datos de entornos privados o trazas de depuración completas de Odoo. Informa sobre vulnerabilidades a través de SECURITY.md.

Licencia

MIT. Ver LICENSE.

Odoo MCP Server