Magenest Odoo MCP Server

Servidor MCP de Magenest Odoo (mgn_mcp_server)

Un módulo de Odoo 19 que expone una instancia de Odoo en vivo a asistentes de IA y agentes a través del Protocolo de Contexto de Modelo (MCP). Permite que clientes compatibles con MCP lean y escriban registros de Odoo mediante llamadas a herramientas impulsadas por lenguaje natural, aplicando los mismos controles de acceso y permisos ya configurados en Odoo.

• Repositorio: MagenestJSC/advanced_mcp_server
• Versión de Odoo: 19.0
• Licencia: OPL-1
• Autor: Magenest

Descripción general

El módulo añade una puerta de enlace JSON-RPC 2.0 (POST /mcp_server) a Odoo que habla un conjunto pequeño y uniforme de "herramientas" en lugar de exponer llamadas ORM/XML-RPC sin procesar. Cada solicitud se ejecuta como un usuario real de Odoo, por lo que las reglas de registro, la seguridad a nivel de campo y el acceso a módulos definidos en Odoo se respetan automáticamente. Sobre esa base, el módulo añade una capa dedicada de control de acceso configurable por el administrador, OAuth 2.1 para clientes basados en navegador, limitación de velocidad y un registro de auditoría de cada llamada.

Características clave

• Superficie de herramientas unificada — un pequeño conjunto de herramientas genéricas (describe, get, search, aggregate, me, count, explain, compare, resources para lecturas; add, edit, drop, run, attach, pipeline para escrituras) cubre modelos arbitrarios de Odoo en lugar de un endpoint por modelo.
• Control de acceso de grano fino — anulaciones por módulo (adv.module.access) y por modelo (adv.model.access) deciden qué modelos y operaciones (lectura/escritura/eliminación/llamadas a métodos) son accesibles a través de la puerta de enlace, independientemente de los permisos normales del usuario en Odoo.
• Herramientas personalizadas — los administradores pueden exponer sus propias acciones de ir.actions.server como herramientas MCP de primera clase (adv.custom.tool), con validación de entrada mediante JSON Schema.
• Dos modos de autenticación
  • Claves API — claves con alcance definido generadas desde el asistente estándar de claves API de Odoo.
  • OAuth 2.1 — un servidor de autorización integrado (server/oauth/) que admite los tipos de concesión estándar, PKCE, registro dinámico de clientes y un endpoint de descubrimiento, para clientes basados en navegador y de terceros.
• Controles de seguridad y abuso — un interruptor maestro de activación/desactivación, limitación de velocidad con ventana deslizante por usuario y por administrador (server/rate_limiter.py), límites de tamaño de solicitud, lista blanca de orígenes CORS y respuestas de error saneadas que nunca filtran rastreos internos (server/sanitizer.py).
• Registro de auditoría — cada llamada se registra en adv.event.log (actor, recurso, operación, cargas de solicitud/respuesta, errores) con retención configurable, independiente de la transacción que la invoca, de modo que una solicitud fallida aún quede registrada.
• Cargas útiles amigables para LLM — selección inteligente de campos (tools/smart_fields.py) y formateadores de texto jerárquicos (tools/formatters.py) recortan y dan forma a la salida de read/fields_get de Odoo para un consumo eficiente de tokens, además de un esquema de URI odoo:// (tools/uri_schema.py) para referenciar campos binarios y adjuntos como recursos MCP.
• Proxy XML-RPC heredado — server/rpc_proxy.py conecta clientes XML-RPC a través de la misma puerta de enlace y el mismo pipeline de auditoría/limitación de velocidad.

Arquitectura

mgn_mcp_server/
├── models/         # Access control, OAuth entities, custom tools, audit log, tool_mixin (adv_tool registry)
├── server/         # HTTP gateway, JSON-RPC dispatcher/protocol, auth, rate limiting, sanitizer, audit writer
│   └── oauth/      # OAuth 2.1 authorization server (grants, endpoints, discovery)
├── tools/          # Field selection, output formatting, odoo:// URI helpers
├── views/          # Backend UI for configuration, access control, audit log, API keys, OAuth clients
├── wizard/         # Module picker / bulk action wizards
├── security/       # Access rights and record rules
└── data/           # Default gateway configuration, OAuth maintenance cron

Las capacidades de lectura y escritura se implementan como métodos Python simples etiquetados con @adv_tool en adv.tool.mixin (ver models/read_tools.py y models/write_tools.py); cualquier módulo que herede este mixin puede contribuir con herramientas adicionales, que se descubren automáticamente mediante un escaneo MRO — sin registro central que editar.

Herramientas disponibles

Herramienta	Tipo	Propósito
describe	lectura	Listar recursos accesibles, o devolver el esquema completo de un modelo
get	lectura	Obtener un único registro por ID, con expansión opcional de relaciones (depth)
search	lectura	Buscar registros mediante un dominio de Odoo o un spec simplificado de clave-valor
aggregate	lectura	Agrupar/dinamizar registros por una o dos dimensiones
me	lectura	Identidad de la sesión actual: usuario, zona horaria, compañía, recursos permitidos, alcance OAuth activo
count	lectura	Contar registros que coinciden con un dominio, sin recuperarlos
explain	lectura	Resumen contextual de un registro: campos clave, actividad reciente, estado, adjuntos
compare	lectura	Comparar dos registros del mismo modelo, campo por campo
resources	lectura	Listar URIs de recursos odoo:// para campos binarios/adjuntos
add	escritura	Crear un registro (admite validación dry_run)
edit	escritura	Actualizar campos específicos en un registro existente
drop	escritura	Eliminar un registro (informa de los registros que se verían afectados por la cascada)
run	escritura	Llamar a un método público del modelo (incluido message_post para actividad)
attach	escritura	Subir un archivo como ir.attachment, devolviendo una URI odoo://
pipeline	escritura	Ejecutar múltiples operaciones add/edit/drop/run de forma atómica, con encadenamiento de resultados

Requisitos

• Odoo 19.0
• Dependencias de Python: authlib>=1.6.12,<1.7.0, defusedxml, packaging
• Dependencias de módulos de Odoo: base, base_setup, mail, rpc, web

Instalación

1. Copie mgn_mcp_server en su ruta de addons de Odoo.
2. Instale las dependencias de Python:

   pip install "authlib>=1.6.12,<1.7.0" defusedxml packaging
   

3. Actualice la lista de aplicaciones e instale Servidor MCP de Magenest Odoo desde el menú de Aplicaciones de Odoo.
4. Vaya a la configuración del módulo para habilitar la puerta de enlace, configurar la limitación de velocidad y establecer el control de acceso para los modelos que desea exponer.

Configuración

Toda la configuración de la puerta de enlace reside en el registro singleton adv.server.config, editable desde la pantalla de Configuración del módulo:

Configuración	Predeterminado	Descripción
Puerta de enlace habilitada	False	Interruptor maestro para el endpoint /mcp_server
OAuth 2.1	True	Habilita el flujo de autorización OAuth 2.1 integrado
Limitación de velocidad	False	Habilita la limitación de solicitudes por usuario
Solicitudes / Minuto (por usuario)	300	Límite de velocidad por usuario cuando la limitación está activa
Solicitudes de administrador / Minuto	0 (= igual que el regular)	Límite más alto para administradores de la puerta de enlace
Registro de eventos	True	Habilita el registro de auditoría en adv.event.log
Retención de registros (días)	30	0 = conservar para siempre
Límite de registros predeterminado	10	Tamaño de página predeterminado para search/aggregate
Límite máximo de registros	100	Tope máximo del tamaño de página
Máximo de campos inteligentes	15	Máximo de campos auto-seleccionados por registro en la salida amigable para LLM
Máximo de elementos relacionados	3	Máximo de registros relacionados auto-obtenidos al expandir relaciones
Orígenes permitidos	(vacío = sin restricciones)	Lista separada por comas de orígenes de navegador permitidos para CORS

El acceso a nivel de modelo se concede mediante registros de Acceso a Módulo Adv MCP / Anulación de Permiso por Modelo Adv MCP, que deciden qué modelos y operaciones son accesibles independientemente de los permisos de grupo normales del usuario en Odoo.

Endpoint

Una vez habilitada, la puerta de enlace es accesible en:

POST /mcp_server
POST /mcp_server/rpc

usando envolturas de solicitud/respuesta JSON-RPC 2.0, autenticadas ya sea con una clave API de Odoo o con un token de portador OAuth 2.1 obtenido a través del servidor de autorización integrado del módulo.

Notas de seguridad

• La puerta de enlace está deshabilitada por defecto — debe activarse explícitamente en la configuración.
• Todo el acceso sigue pasando por las reglas de registro y la seguridad de campos propias de Odoo, además de la capa de control de acceso del módulo.
• Los errores internos se sanean antes de devolverse a los clientes; solo las excepciones reconocidas de Odoo (UserError, AccessError, ValidationError, MissingError) muestran su mensaje, todo lo demás devuelve un error genérico.
• run (llamadas a métodos) está bloqueado para internos de ORM y métodos privados (con prefijo de guion bajo), y debe permitirse explícitamente por modelo.