Odoo
Interactúa con sistemas ERP de Odoo, permitiendo que asistentes de IA accedan y gestionen datos empresariales como contactos, ventas y proyectos.
Documentación
Servidor MCP para Odoo
Un servidor MCP que permite a asistentes de IA como Claude interactuar con sistemas ERP de Odoo. Accede a datos de negocio, busca registros, crea nuevas entradas, actualiza datos existentes y gestiona tu instancia de Odoo mediante lenguaje natural.
¡Funciona con cualquier instancia de Odoo! Usa el modo YOLO para pruebas rápidas y demostraciones con cualquier instalación estándar de Odoo. Para seguridad empresarial, controles de acceso y uso en producción, instala el módulo MCP de Odoo.
Características
- 🔍 Busca y recupera cualquier registro de Odoo (clientes, productos, facturas, etc.)
- ✨ Crea nuevos registros con validación de campos y comprobación de permisos
- ✏️ Actualiza datos existentes con manejo inteligente de campos
- 🗑️ Elimina registros respetando los permisos a nivel de modelo
- 🔢 Cuenta registros que coincidan con criterios específicos
- 📋 Inspecciona campos de modelos para comprender la estructura de datos
- 📊 Agregación del lado del servidor — agrupa, suma y cuenta sin extraer filas sin procesar
- ⚡ Acciones de flujo de trabajo — invoca métodos públicos de negocio (publicar factura, confirmar pedido de venta, etc.) mediante una vía de escape opcional
- 📎 Recursos binarios y adjuntos — obtén imágenes, documentos y archivos
ir.attachmentmediante URI de recursos - 👤 Contexto de sesión personalizado — el usuario conectado, la zona horaria y el alcance de la empresa se inyectan en las instrucciones de la sesión
- 🔐 Acceso seguro con clave API o autenticación de nombre de usuario/contraseña
- 🎯 Paginación inteligente para conjuntos de datos grandes
- 🧠 Selección inteligente de campos — elige automáticamente los campos más relevantes por modelo
- 💬 Salida optimizada para LLM con formato de texto jerárquico
- 🌍 Soporte multilingüe — obtén respuestas en tu idioma preferido
- 🚀 Modo YOLO para acceso rápido con cualquier instancia de Odoo (sin necesidad de módulo)
Instalación
Requisitos previos
- Python 3.10 o superior
- Acceso a una instancia de Odoo:
- Modo estándar (producción): Versión 16.0+ con el módulo MCP de Odoo instalado
- Modo YOLO (pruebas/demostraciones): Cualquier versión de Odoo con XML-RPC habilitado (sin necesidad de módulo)
Instalar UV primero
El servidor MCP se ejecuta en tu computadora local (donde está instalado Claude Desktop), no en tu servidor de Odoo. Debes instalar UV en tu máquina local:
macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Después de la instalación, reinicia tu terminal para asegurarte de que UV esté en tu PATH.
Instalación mediante la configuración de MCP (recomendado)
Añade esta configuración a tu configuración de MCP:
{
"mcpServers": {
"odoo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here"
}
}
}
}
Claude Desktop
Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"odoo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}
Claude Code
Añade a .mcp.json en la raíz de tu proyecto:
{
"mcpServers": {
"odoo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}
O usa la CLI:
claude mcp add odoo \
--env ODOO_URL=https://your-odoo-instance.com \
--env ODOO_API_KEY=your-api-key-here \
--env ODOO_DB=your-database-name \
-- uvx mcp-server-odoo
Cursor
Añade a ~/.cursor/mcp.json:
{
"mcpServers": {
"odoo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}
VS Code (con GitHub Copilot)
Añade a .vscode/mcp.json en tu espacio de trabajo:
{
"servers": {
"odoo": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}
Nota: VS Code usa
"servers"como clave raíz, no"mcpServers".
Windsurf
Añade a ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"odoo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}
Zed
Añade a ~/.config/zed/settings.json:
{
"context_servers": {
"odoo": {
"command": {
"path": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}
}
Métodos de instalación alternativos
Usando Docker
Ejecuta con Docker — no se requiere instalación de Python:
{
"mcpServers": {
"odoo": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "ODOO_URL=http://host.docker.internal:8069",
"-e", "ODOO_API_KEY=your-api-key-here",
"ivnvxd/mcp-server-odoo"
]
}
}
}
Nota: Usa
host.docker.internalen lugar delocalhostpara conectarte a Odoo que se ejecuta en la máquina host.
Para transporte HTTP:
docker run --rm -p 8000:8000 \
-e ODOO_URL=http://host.docker.internal:8069 \
-e ODOO_API_KEY=your-api-key-here \
ivnvxd/mcp-server-odoo --transport streamable-http --host 0.0.0.0
⚠️ Seguridad: el transporte HTTP no tiene autenticación integrada — cualquiera que pueda alcanzar el puerto obtiene acceso a Odoo mediante las credenciales del servidor. Publica el puerto solo en redes de confianza, o colócalo detrás de un proxy inverso con autenticación. Consulta Opciones de transporte.
La imagen también está disponible en GHCR: ghcr.io/ivnvxd/mcp-server-odoo
Usando pip
# Install globally
pip install mcp-server-odoo
# Or use pipx for isolated environment
pipx install mcp-server-odoo
Luego usa mcp-server-odoo como comando en tu configuración de MCP.
Desde el código fuente
git clone https://github.com/ivnvxd/mcp-server-odoo.git
cd mcp-server-odoo
pip install -e .
Luego usa la ruta completa al paquete en tu configuración de MCP.
Configuración
Variables de entorno
El servidor requiere las siguientes variables de entorno:
| Variable | Requerida | Descripción | Ejemplo |
|---|---|---|---|
ODOO_URL | Sí | URL de tu instancia de Odoo | https://mycompany.odoo.com |
ODOO_API_KEY | Sí* | Clave API para autenticación | 0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd |
ODOO_USER | Sí* | Nombre de usuario (si no se usa clave API) | admin |
ODOO_PASSWORD | Sí* | Contraseña (si no se usa clave API) | admin |
ODOO_DB | No | Nombre de la base de datos (se detecta automáticamente si no se establece) | mycompany |
ODOO_LOCALE | No | Idioma/locale para respuestas de Odoo | es_ES, fr_FR, de_DE |
ODOO_YOLO | No | Modo YOLO - omite la seguridad de MCP (⚠️ SOLO DESARROLLO) | off, read, true |
ODOO_MCP_ENABLE_METHOD_CALLS | No | Habilita la herramienta call_model_method — requiere ODOO_YOLO=true (⚠️ Peligroso, consulta call_model_method) | false, true |
*Se requiere ODOO_API_KEY o ambos ODOO_USER y ODOO_PASSWORD. En modo YOLO, ODOO_USER es obligatorio incluso cuando se usa una clave API.
Notas:
- Si el listado de bases de datos está restringido en tu servidor, debes especificar
ODOO_DB - Se recomienda la autenticación con clave API para mayor seguridad
- El servidor también carga variables de entorno desde un archivo
.enven el directorio de trabajo
Configuración avanzada
| Variable | Predeterminado | Descripción |
|---|---|---|
ODOO_MCP_DEFAULT_LIMIT | 10 | Número predeterminado de registros devueltos por búsqueda |
ODOO_MCP_MAX_LIMIT | 100 | Límite máximo permitido de registros por solicitud |
ODOO_MCP_MAX_SMART_FIELDS | 15 | Máximo de campos devueltos por la selección inteligente de campos |
ODOO_MCP_LOG_LEVEL | INFO | Nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
ODOO_MCP_LOG_JSON | false | Habilita la salida de registro JSON estructurada |
ODOO_MCP_LOG_FILE | — | Ruta para archivo de registro rotativo (10 MB, 5 copias de seguridad) |
ODOO_MCP_LOG_FORMAT | — | Cadena de formato de registro personalizada de Python (predeterminado: %(asctime)s - %(name)s - %(levelname)s - %(message)s) |
ODOO_MCP_SLOW_OPERATION_THRESHOLD_MS | 1000 | Umbral en milisegundos por encima del cual una operación se registra como lenta |
ODOO_MCP_TRANSPORT | stdio | Tipo de transporte (stdio, streamable-http) |
ODOO_MCP_HOST | localhost | Host para vincular el transporte HTTP |
ODOO_MCP_PORT | 8000 | Puerto para vincular el transporte HTTP |
ODOO_MCP_ALLOWED_HOSTS | — | Cabeceras Host separadas por comas para aceptar en el transporte HTTP (protección contra rebinding de DNS). Establecer cuando se ejecuta streamable-http detrás de un proxy inverso que reenvía un host externo, p. ej. odoo.example.com,localhost. Los literales IPv6 pueden ir entre corchetes o sin ellos ([::1]:8000, ::1). Si no se establece, la protección solo se activa automáticamente para un bind de loopback — vincular cualquier otro host (p. ej. 0.0.0.0) se ejecuta sin validación de Host/Origin en absoluto. |
ODOO_MCP_SESSION_IDLE_TIMEOUT | — | Segundos de inactividad antes de que una sesión de streamable-http se cierre y su estado del lado del servidor se libere, p. ej. 600. Si no se establece, las sesiones nunca caducan. |
ODOO_MCP_MAX_BINARY_SIZE | 52428800 | Máximo de bytes devueltos por un único resources/read binario/adjunto. Se comprueba antes de obtener la carga útil (una sonda bin_size para campos de registro, el file_size almacenado para adjuntos), por lo que una lectura de tamaño excesivo se rechaza con un error claro en lugar de cargarse en memoria y volver a codificarse en base64 para la transmisión. |
Opciones de transporte
El servidor admite múltiples protocolos de transporte para diferentes casos de uso:
1. stdio (predeterminado)
Transporte de entrada/salida estándar: utilizado por aplicaciones de escritorio de IA como Claude Desktop.
# Default transport - no additional configuration needed
uvx mcp-server-odoo
2. streamable-http
Transporte HTTP estándar para acceso de estilo API REST y conectividad remota.
⚠️ Seguridad: este transporte no tiene autenticación de cliente integrada. Cualquier cliente que pueda alcanzar el puerto puede usar todas las herramientas y recursos con las credenciales de Odoo que posee el servidor, incluidas escrituras en modo YOLO de acceso completo. Mantén el bind
localhostpredeterminado a menos que la red sea de confianza, y coloca el servidor detrás de un proxy inverso con autenticación (p. ej. nginx con autenticación básica u OAuth) para acceso remoto. El servidor registra una advertencia al vincular un host que no sea de loopback.
# Run with HTTP transport (localhost only — safe default)
uvx mcp-server-odoo --transport streamable-http --port 8000
# Binding 0.0.0.0 exposes the server to the network — see the security note above
uvx mcp-server-odoo --transport streamable-http --host 0.0.0.0 --port 8000
# Or use environment variables
export ODOO_MCP_TRANSPORT=streamable-http
export ODOO_MCP_HOST=0.0.0.0
export ODOO_MCP_PORT=8000
uvx mcp-server-odoo
El endpoint HTTP estará disponible en: http://localhost:8000/mcp/
Nota: el transporte SSE (Server-Sent Events) ha quedado obsoleto en la versión 2025-03-26 del protocolo MCP. Usa el transporte streamable-http para comunicación basada en HTTP. Requiere la biblioteca MCP v1.27.0 o superior.
Ejecutar transporte streamable-http para acceso remoto
{
"mcpServers": {
"odoo-remote": {
"command": "uvx",
"args": ["mcp-server-odoo", "--transport", "streamable-http", "--port", "8080"],
"env": {
"ODOO_URL": "https://your-odoo-instance.com",
"ODOO_API_KEY": "your-api-key-here",
"ODOO_DB": "your-database-name"
}
}
}
}
Configurar Odoo
-
Instala el módulo MCP:
- Descarga el módulo mcp_server
- Instálalo en tu instancia de Odoo
- Navega a Ajustes > Servidor MCP
-
Habilita modelos para acceso MCP:
- Ve a Ajustes > Servidor MCP > Modelos habilitados
- Añade los modelos a los que quieras acceder (p. ej., res.partner, product.product)
- Configura permisos (lectura, escritura, creación, eliminación) por modelo
-
Genera una clave API:
- Ve a Ajustes > Usuarios y empresas > Usuarios
- Selecciona tu usuario
- En la pestaña "Claves API", crea una nueva clave
- Copia la clave para tu configuración de MCP
Modo YOLO (solo desarrollo/pruebas) ⚠️
El modo YOLO permite que el servidor MCP se conecte directamente a cualquier instancia estándar de Odoo sin requerir el módulo MCP. Este modo omite todos los controles de seguridad de MCP y está destinado SOLO para desarrollo, pruebas y demostraciones.
🚨 ADVERTENCIA: ¡Nunca uses el modo YOLO en entornos de producción!
Niveles del modo YOLO
-
Modo de solo lectura (
ODOO_YOLO=read):- Permite todas las operaciones de lectura (búsqueda, lectura, conteo)
- Bloquea todas las operaciones de escritura (crear, actualizar, eliminar)
- Seguro para demostraciones y pruebas
- Muestra indicadores de "SOLO LECTURA" en las respuestas
-
Modo de acceso completo (
ODOO_YOLO=true):- Permite TODAS las operaciones sin restricciones
- Acceso CRUD completo a todos los modelos
- EXTREMADAMENTE PELIGROSO — úsalo solo en entornos aislados
- Muestra advertencias de "ACCESO COMPLETO" en las respuestas
Configuración del modo YOLO
Modo YOLO de solo lectura (más seguro para demostraciones)
{
"mcpServers": {
"odoo-demo": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "http://localhost:8069",
"ODOO_USER": "admin",
"ODOO_PASSWORD": "admin",
"ODOO_DB": "demo",
"ODOO_YOLO": "read"
}
}
}
}
Modo YOLO de acceso completo (⚠️ usar con extrema precaución)
{
"mcpServers": {
"odoo-test": {
"command": "uvx",
"args": ["mcp-server-odoo"],
"env": {
"ODOO_URL": "http://localhost:8069",
"ODOO_USER": "admin",
"ODOO_PASSWORD": "admin",
"ODOO_DB": "test",
"ODOO_YOLO": "true"
}
}
}
}
Cuándo usar el modo YOLO
✅ Usos apropiados:
- Desarrollo local con datos de prueba
- Demostraciones rápidas con datos no sensibles
- Pruebas de clientes MCP antes de instalar el módulo MCP
- Prototipado en entornos aislados
❌ Nunca usar para:
- Entornos de producción
- Instancias con datos reales de clientes
- Servidores de desarrollo compartidos
- Cualquier entorno con información sensible
Notas de seguridad del modo YOLO
- Se conecta directamente a los endpoints XML-RPC estándar de Odoo
- Omite todos los controles de acceso y restricciones de modelos de MCP
- No se aplica limitación de velocidad
- Todas las operaciones se registran pero no se restringen
- El listado de modelos muestra más de 200 modelos en lugar de solo los habilitados
Ejemplos de uso
Una vez configurado, puedes pedirle a Claude:
Buscar y recuperar:
- "Muéstrame todos los clientes de España"
- "Encuentra productos con stock inferior a 10 unidades"
- "Lista las órdenes de venta de hoy superiores a $1000"
- "Busca facturas impagadas del mes pasado"
- "Cuenta cuántos empleados activos tenemos"
- "Muéstrame la información de contacto de Microsoft"
Crear y gestionar:
- "Crea un nuevo contacto de cliente para Acme Corporation"
- "Añade un nuevo producto llamado 'Premium Widget' con precio $99.99"
- "Crea un evento de calendario para mañana a las 2 PM"
- "Actualiza el número de teléfono del cliente John Doe a +1-555-0123"
- "Cambia el estado de la orden SO/2024/001 a confirmada"
- "Elimina el contacto de prueba que creamos antes"
Herramientas disponibles
search_records
Busca registros en cualquier modelo de Odoo con filtros.
{
"model": "res.partner",
"domain": [["is_company", "=", true], ["country_id.code", "=", "ES"]],
"fields": ["name", "email", "phone"],
"limit": 10
}
Opciones de selección de campos:
- Omite
fieldso establécelo ennull: Devuelve una selección inteligente de campos comunes - Especifica una lista de campos: Devuelve solo esos campos específicos
- Una lista vacía
[]se trata comonull(valores predeterminados inteligentes) - Usa
["__all__"]: Devuelve todos los campos (usar con precaución) — los campos similares a credenciales se omiten y se enumeran en elnotede la respuesta; solicítalos explícitamente por nombre si es necesario
get_record
Recupera un registro específico por ID.
{
"model": "res.partner",
"record_id": 42,
"fields": ["name", "email", "street", "city"]
}
Opciones de selección de campos:
- Omite
fieldso establécelo ennull: Devuelve una selección inteligente de campos comunes con metadatos - Especifica una lista de campos: Devuelve solo esos campos específicos
- Una lista vacía
[]se trata comonull(valores predeterminados inteligentes) - Usa
["__all__"]: Devuelve todos los campos — los campos similares a credenciales se omiten y se indican en los metadatos de la respuesta; solicítalos explícitamente por nombre si es necesario
Las respuestas también incluyen related_summaries: nombres para mostrar de colecciones one2many/many2many que contienen como máximo 5 IDs, para que las relaciones pequeñas sean legibles sin búsquedas adicionales.
get_fields
Describe los campos de un modelo: tipo, etiqueta, obligatorio/solo lectura, destino de la relación y opciones de selección. Úsalo para descubrir el esquema de un modelo antes de leer o escribir registros. Omite attributes para el conjunto predeterminado seleccionado (type, string, required, readonly, relation, selection); una lista explícita reemplaza el conjunto seleccionado: incluye los valores predeterminados en tu lista si aún los necesitas (por ejemplo, ["type", "string", "help", "store"]). Omite field_names para describir todos los campos del modelo. Una lista vacía [] para cualquiera de los parámetros se trata como si se omitiera.
{
"model": "res.partner",
"field_names": ["name", "email", "parent_id"]
}
get_current_context
Devuelve el contexto de la sesión actual: el usuario conectado, su zona horaria, la empresa activa más cualquier otra empresa permitida, y las pautas de manejo de fecha y hora UTC. Útil cuando no estás seguro de qué usuario o empresa ejecuta una solicitud, o cómo interpretar las fechas y horas. Los clientes compatibles con la especificación también reciben este contexto a través de las instrucciones de respuesta initialize.
{}
list_models
Lista todos los modelos habilitados para acceso MCP.
{}
list_resource_templates
Lista las plantillas de URI de recursos disponibles y sus patrones.
{}
create_record
Crea un nuevo registro en Odoo.
{
"model": "res.partner",
"values": {
"name": "New Customer",
"email": "customer@example.com",
"is_company": true
}
}
update_record
Actualiza un registro existente.
{
"model": "res.partner",
"record_id": 42,
"values": {
"phone": "+1234567890",
"website": "https://example.com"
}
}
delete_record
Elimina un registro de Odoo.
{
"model": "res.partner",
"record_id": 42
}
post_message
Publica un mensaje en el chatter de un registro (mail.thread). subtype="note" (predeterminado) es un registro interno; subtype="comment" notifica a los seguidores. Establece body_is_html=true para marcado HTML. El subject opcional establece una línea de asunto del mensaje; los partner_ids y attachment_ids opcionales hacen referencia a partners y adjuntos existentes.
{
"model": "res.partner",
"record_id": 42,
"body": "Called customer, will follow up Tuesday"
}
{
"model": "sale.order",
"record_id": 17,
"body": "<p>Shipping confirmed for Monday</p>",
"subtype": "comment",
"body_is_html": true
}
aggregate_records
Agregación del lado del servidor. Úsalo siempre que la pregunta sea "totales/recuentos/agrupaciones" en lugar de "lista de registros": transfiere el trabajo a PostgreSQL en lugar de extraer filas sin procesar. Se envía a formatted_read_group en Odoo 19+ (el nuevo método dedicado) y recurre a read_group con normalización de respuesta en versiones anteriores. Los llamadores ven una forma de respuesta consistente en todas las versiones compatibles. Cuando se omite aggregates, el valor predeterminado es ["__count"] para que cada grupo siempre lleve un recuento. Cuando existen más grupos más allá de la página solicitada, la respuesta establece has_more: true y un next_hint con el desplazamiento de seguimiento.
{
"model": "sale.order",
"groupby": ["date_order:month"],
"aggregates": ["amount_total:sum"],
"domain": [["state", "in", ["sale", "done"]]]
}
{
"model": "res.partner",
"groupby": ["country_id"]
}
call_model_method
Vía de escape genérica de XML-RPC execute_kw: invoca métodos comerciales públicos, para acciones de flujo de trabajo no cubiertas por CRUD (publicar factura, confirmar orden de venta, validar albarán, etc.). Disponible solo cuando tanto ODOO_YOLO=true (YOLO completo) como ODOO_MCP_ENABLE_METHOD_CALLS=true están establecidos; de lo contrario, la herramienta no se registra. Solo se aceptan identificadores Python ASCII públicos como nombres de métodos: se rechazan los nombres con puntos, guiones, espacios, no ASCII y los prefijados con _.
Algunas llamadas están bloqueadas por seguridad incluso en modo YOLO completo:
- Modelos
ir.actions.*/ir.cron— sus métodos se ejecutan con privilegios elevados (acciones de servidor, trabajos programados) run/method_direct_triggeren cualquier modelo — el mismo riesgo de escalada a través de proxies- Primitivas CRUD/acceso a datos de ORM (
create,write,unlink,read,search*,copy,sudo, ...) — usa las herramientas dedicadas en su lugar - Métodos
web_*— la familia de acceso a datos del cliente web
Los resultados de la lista se truncan a 100 elementos.
[!ADVERTENCIA] Esta herramienta aún puede invocar métodos de flujo de trabajo destructivos (por ejemplo,
button_draft,action_cancel,toggle_active, métodos personalizados). Habilítala solo en entornos confiables donde aceptes el radio de impacto. Las reglas de registro y los ACL de Odoo aún se aplican para el usuario autenticado.
{
"model": "account.move",
"method": "action_post",
"arguments": [[42]]
}
{
"model": "sale.order",
"method": "action_confirm",
"arguments": [[7]],
"keyword_arguments": {"context": {"lang": "en_US"}}
}
Selección inteligente de campos
Cuando omites el parámetro fields (o lo estableces en null), el servidor selecciona automáticamente los campos más relevantes para cada modelo usando un algoritmo de puntuación:
- Campos esenciales como
id,name,display_nameyactivesiempre se incluyen - Campos relevantes para el negocio (estado, monto, correo electrónico, teléfono, partner, etc.) tienen prioridad
- Campos técnicos (hilos de mensajes, seguimiento de actividad, metadatos del sitio web) se excluyen
- Campos costosos (binarios, HTML, texto grande) se omiten; los campos calculados no almacenados se despriorizan
- Campos similares a credenciales (nombres que terminan en
*password,*_passcomosmtp_pass,passwd,*secret,*_token,*apikey, o un compuesto*_keycomoapi_key/secret_key) se excluyen de los valores predeterminados inteligentes y se omiten de las lecturas["__all__"]con una nota explicativa: solicitar dicho campo explícitamente por nombre aún lo devuelve
El límite predeterminado es de 15 campos por solicitud. Las respuestas incluyen metadatos que muestran qué campos se devolvieron y cuántos campos totales están disponibles. Puedes ajustar el límite con ODOO_MCP_MAX_SMART_FIELDS o omitirlo por completo con fields: ["__all__"].
Recursos
El servidor también proporciona acceso directo a los datos de Odoo a través de URI de recursos:
| Patrón de URI | Descripción |
|---|---|
odoo://{model}/record/{id} | Recupera un registro específico por ID |
odoo://{model}/search | Busca registros con configuración predeterminada (primeros 10 registros) |
odoo://{model}/count | Cuenta todos los registros en un modelo |
odoo://{model}/fields | Obtiene definiciones de campos y metadatos para un modelo |
odoo://{model}/record/{id}/{field} | Obtiene un campo binario/imagen de un registro, servido con el mimeType correcto |
odoo://attachment/{id} | Obtiene un ir.attachment por ID (los adjuntos tipo URL devuelven su URL como texto) |
Ejemplos:
odoo://res.partner/record/1— Obtener partner con ID 1odoo://product.product/search— Listar los primeros 10 productosodoo://res.partner/count— Contar todos los partnersodoo://product.product/fields— Mostrar todos los campos de productosodoo://res.partner/record/1/image_128— Obtener la imagen de avatar del partner 1odoo://attachment/42— Descargar el adjunto 42
Los campos binarios poblados en los resultados de get_record/search_records se devuelven como estos URI de recursos en lugar de base64 en línea: lee el URI para recuperar los bytes reales. El contenido binario se sirve exclusivamente a través de recursos MCP: los resultados de las herramientas llevan URI, nunca base64 en línea, por lo que tu cliente MCP debe admitir resources/read para obtenerlo.
Las lecturas de recursos de registros y búsquedas omiten los campos similares a credenciales de la misma manera que las lecturas masivas de las herramientas: para leer dicho campo, solicítalo explícitamente por nombre a través del parámetro fields de las herramientas.
Las lecturas binarias y de adjuntos se sirven completas, hasta ODOO_MCP_MAX_BINARY_SIZE (50 MB predeterminado). El tamaño se verifica antes de obtener la carga útil, por lo que un campo o adjunto de tamaño excesivo se rechaza con un error claro en lugar de almacenarse en un búfer en una respuesta correspondientemente grande.
Nota: Los URI de recursos no admiten parámetros de consulta (como
?domain=...). Para filtrado, paginación y selección de campos, usa la herramientasearch_recordsen su lugar.
Cómo funciona
AI Assistant (Claude, Copilot, etc.)
↓ MCP Protocol (stdio or HTTP)
mcp-server-odoo
↓ XML-RPC
Odoo Instance
El servidor traduce las llamadas de herramientas MCP en solicitudes XML-RPC de Odoo. Maneja autenticación, control de acceso, selección de campos, formato de datos y manejo de errores, presentando los datos de Odoo en un formato de texto jerárquico amigable para LLM.
Seguridad
- Usa siempre HTTPS en entornos de producción
- Mantén tus claves API seguras y gíralas regularmente
- Configura el acceso a los modelos con cuidado: solo habilita los modelos necesarios
- El módulo MCP respeta los derechos de acceso integrados y las reglas de registro de Odoo
- Cada clave API está vinculada a un usuario específico con sus permisos
Solución de problemas
Problemas de conexión
Si estás recibiendo errores de conexión:
- Verifica que tu URL de Odoo sea correcta y accesible
- Comprueba que el módulo MCP esté instalado: visita
https://your-odoo.com/mcp/health - Asegúrate de que tu firewall permita conexiones a Odoo
Errores de autenticación
Si la autenticación falla:
- Verifica que tu clave API esté activa en Odoo
- Comprueba que el usuario tenga los permisos apropiados
- Intenta regenerar la clave API
- Para autenticación con nombre de usuario/contraseña, asegúrate de que 2FA no esté habilitado
Errores de acceso a modelos
Si no puedes acceder a ciertos modelos:
- Ve a Configuración > Servidor MCP > Modelos habilitados en Odoo
- Asegúrate de que el modelo esté en la lista y tenga los permisos apropiados
- Comprueba que tu usuario tenga acceso a ese modelo en la configuración de seguridad de Odoo
Error "spawn uvx ENOENT"
Este error significa que UV no está instalado o no está en tu PATH:
Solución 1: Instalar UV (consulta la sección de Instalación anterior)
Solución 2: Problema de PATH en macOS Claude Desktop en macOS no hereda el PATH de tu shell. Intenta:
- Sal de Claude Desktop por completo (Cmd+Q)
- Abre Terminal
- Inicia Claude desde Terminal:
open -a "Claude"
Solución 3: Usar ruta completa Encuentra la ubicación de UV y usa la ruta completa:
which uvx
# Example output: /Users/yourname/.local/bin/uvx
Luego actualiza tu configuración:
{
"command": "/Users/yourname/.local/bin/uvx",
"args": ["mcp-server-odoo"]
}
Problemas de configuración de base de datos
Si ves "Acceso denegado" al listar bases de datos:
- Esto es normal: algunas instancias de Odoo restringen el listado de bases de datos por seguridad
- Asegúrate de especificar
ODOO_DBen tu configuración - El servidor usará tu base de datos especificada sin validación
Ejemplo de configuración:
{
"env": {
"ODOO_URL": "https://your-odoo.com",
"ODOO_API_KEY": "your-key",
"ODOO_DB": "your-database-name"
}
}
Nota: ODOO_DB es obligatorio si el listado de bases de datos está restringido en tu servidor.
Error "SSL: CERTIFICATE_VERIFY_FAILED"
Este error ocurre cuando Python no puede verificar los certificados SSL, a menudo en macOS o redes corporativas.
Solución: Agrega la ruta del certificado SSL a tu configuración de entorno:
{
"env": {
"ODOO_URL": "https://your-odoo.com",
"ODOO_API_KEY": "your-key",
"SSL_CERT_FILE": "/etc/ssl/cert.pem"
}
}
Esto le indica a Python dónde encontrar el paquete de certificados SSL del sistema para conexiones HTTPS. La ruta /etc/ssl/cert.pem es la ubicación estándar en la mayoría de los sistemas.
Modo de depuración
Habilita el registro de depuración para obtener más información:
{
"env": {
"ODOO_URL": "https://your-odoo.com",
"ODOO_API_KEY": "your-key",
"ODOO_MCP_LOG_LEVEL": "DEBUG"
}
}
Desarrollo
Ejecutar desde el código fuente
# Clone the repository
git clone https://github.com/ivnvxd/mcp-server-odoo.git
cd mcp-server-odoo
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest --cov
# Run the server
python -m mcp_server_odoo
# Check version
python -m mcp_server_odoo --version
Pruebas con MCP Inspector
# Using uvx
npx @modelcontextprotocol/inspector uvx mcp-server-odoo
# Using local installation
npx @modelcontextprotocol/inspector python -m mcp_server_odoo
Pruebas
Ejecutar pruebas
# Unit tests (no Odoo needed)
uv run pytest -m "not yolo and not mcp" --cov
# YOLO integration tests (vanilla Odoo, no MCP module)
uv run pytest -m "yolo" -v
# MCP integration tests (Odoo + MCP module installed)
uv run pytest -m "mcp" -v
# All tests
uv run pytest --cov
# Run specific test categories
uv run pytest tests/test_tools.py -v
uv run pytest tests/test_server_foundation.py -v
Licencia
Este proyecto está bajo la Licencia Pública de Mozilla 2.0 (MPL-2.0): consulta el archivo LICENSE para más detalles.
Contribuciones
¡Las contribuciones son muy bienvenidas! Consulta la guía CONTRIBUTING para más detalles.
Soporte
¡Gracias por usar este proyecto! Si te resulta útil y deseas apoyar mi trabajo, considera invitarme a un café. ¡Tu apoyo es muy apreciado!
¡Y no olvides darle una estrella al proyecto si te gusta! :star:
