Odoo集成协议

MCP Odoo - Model Context Protocol para Odoo

MCP server que permite interacturar con Odoo desde cualquier IDE compatible con MCP (OpenCode, Cursor, Claude Desktop, etc.)

Características

• 🔐 Login con credenciales propias - Cada usuario usa sus credenciales de Odoo
• Gestión de tareas - Lista tus tareas, filtra por proyecto y estado
• Contexto de tickets - Reúne descripción, chatter, evidencia, ramas, etapas y horas
• Timesheets seguros - Valida tarea, proyecto, duplicados y propiedad de líneas
• Ramas GitLab - Verifica referencias y divergencia antes de crear un MR
• 🔄 Genérico - Funciona con cualquier instancia de Odoo 17+

Instalación

git clone https://github.com/Igabr13l/mcp-odoo.git
cd mcp-odoo
npm install
npm run build

El servidor se compila en dist/src. Para desarrollo:

npm run typecheck
npm test
npm start

Configuración por IDE

OpenCode

Agregar en opencode.json de tu workspace:

{
  "mcp": {
    "odoo": {
      "type": "local",
      "command": ["node", "/ruta/absoluta/a/mcp-odoo/dist/src/index.js"],
      "enabled": true
    }
  }
}

Cursor / Claude Desktop

Agregar en cursor.json o claude_desktop_config.json:

{
  "mcpServers": {
    "odoo": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp-odoo/dist/src/index.js"]
    }
  }
}

VS Code (con extension MCP)

En settings.json:

{
  "mcpServers": {
    "odoo": {
      "command": "node",
      "args": ["C:\\ruta\\a\\mcp-odoo\\dist\\src\\index.js"]
    }
  }
}

Windsurf

En ~/.windsurf/config.json o en el archivo de configuración del proyecto:

{
  "mcp": {
    "odoo": {
      "type": "local",
      "command": ["node", "/ruta/a/mcp-odoo/dist/src/index.js"]
    }
  }
}

Uso

1. Login (obligatorio)

Primero, iniciá sesión con tus credenciales de Odoo:

odoo_login({
  url: "https://odoo.tuempresa.com",
  db: "nombre_db",
  login: "tu@email.com",
  password: "tu_password"
})

2. Herramientas disponibles

3. Ejemplos de uso

Ver mis tareas en progreso

odoo_get_my_tasks({ state: "in_progress" })

Ver tareas de un proyecto específico

odoo_get_my_tasks({ project_id: 7, state: "in_progress" })

Ver mis proyectos (donde tengo tickets)

odoo_get_my_projects({})

Ver tickets con filtros

odoo_get_tickets({ mine: true, state: "to_do", search: "whatsapp", limit: 50 })

Ver detalle de una tarea con ramas GitLab

odoo_get_task_detail({ task_id: 9646 })

Leer mensajes, notas y adjuntos

odoo_get_ticket_messages({ task_id: 9646, include_system: false })
odoo_get_ticket_attachments({ task_id: 9646 })
odoo_get_ticket_images({ task_id: 9646, limit: 5 })
odoo_get_ticket_video_frames({ task_id: 9646, frames: 4 })

Los videos se listan con nombre, tipo MIME, tamaño y URL cuando Odoo guarda una. MCP no define contenido de video nativo, por lo que el servidor no carga el binario del video en el contexto. API keys, tokens y passwords se enmascaran por defecto en descripciones y mensajes.

La extracción de fotogramas requiere ffmpeg y ffprobe instalados localmente.

Ver tablero y estado GitLab

odoo_get_my_board({ project_id: 7 })
odoo_get_gitlab_status({ task_id: 11244 })

La creación de una fila GitLab, una rama o un merge request requiere confirm: true. Las operaciones son idempotentes cuando Odoo ya tiene el recurso registrado. Antes de crear un MR, el MCP obtiene la divergencia real y compara los árboles resultantes; rechaza ramas sin commits propios o cuyo árbol es idéntico al merge base. El MCP no fusiona MRs.

Editar una tarea (asignados, descripción y estado)

odoo_update_task({
  task_id: 9646,
  assignee_user_ids: [16],
  description: "Actualizar validaciones de WhatsApp",
  state: "in_progress"
})

También podés usar stage_id o stage_name en vez de state.

Ver ramas GitLab de una tarea

odoo_get_task_gitlab_branches({ task_id: 9646 })

Cargar horas

odoo_create_timesheet({
  task_id: 9646,
  project_id: 7,
  date: "2026-03-01",
  hours: 2,
  description: "Implementación de feature X"
})

Las altas y modificaciones de timesheets se serializan dentro de cada proceso MCP para que la verificación de duplicados y la escritura formen una única sección crítica. Esto no coordina procesos MCP distintos ni otros clientes de Odoo: la idempotencia entre procesos y a nivel servidor sigue siendo responsabilidad de Odoo.

Ver horas cargadas un día específico

odoo_get_my_timesheets({ date: "2026-02-27" })

Ver horas cargadas en un rango de fechas

odoo_get_my_timesheets({ date_from: "2026-02-01", date_to: "2026-02-28" })

Ver horas de un proyecto específico

odoo_get_my_timesheets({ project_id: 7, date_from: "2026-02-01", date_to: "2026-02-28" })

Configuración de Variables de Entorno

Podés configurar valores por defecto:

export ODOO_URL="https://odoo.tuempresa.com"
export ODOO_DB="nombre_db"

Pero seguís necesitando hacer login con tu usuario y password.

La sesión es única por proceso y se reutiliza durante toda la ejecución. El MCP no reautentica periódicamente: Odoo valida las credenciales en cada operación execute_kw. Si varias herramientas arrancan al mismo tiempo sin un uid persistido, comparten un único intento de autenticación.

El timeout HTTP por defecto es de 15 segundos. Puede configurarse entre 1 y 120 segundos con ODOO_REQUEST_TIMEOUT_MS.

Las lecturas con errores transitorios de red o timeout se reintentan una sola vez. Las escrituras nunca se reintentan automáticamente: si el transporte falla, el resultado se marca como incierto y requiere verificar Odoo antes de repetir. El backoff de lectura se configura con ODOO_RETRY_BACKOFF_MS.

La sesión persistida se guarda con permisos 0600 y contiene las credenciales necesarias para JSON-RPC. Puede cambiarse su ubicación con ODOO_SESSION_FILE.

La verificación remota de GitLab permite gitlab.solunika.com por defecto. Para otras instalaciones, configurá una lista separada por comas en ODOO_GITLAB_ALLOWED_HOSTS.

Si ODOO_GITLAB_TOKEN está configurado, odoo_get_gitlab_status consulta la API v4 de GitLab con PRIVATE-TOKEN para informar estado, conflictos, pipelines y aprobaciones del merge request. Las redirecciones no se siguen para evitar enviar el token a otro origen, y el token nunca se incluye en la respuesta. El timeout de estas consultas es de 15 segundos y puede configurarse entre 1 y 120 segundos mediante ODOO_GITLAB_API_TIMEOUT_MS.

La inspección Git informa divergencia, merge base, hashes de árbol y si el árbol de la rama difiere del merge base. Una rama solo se considera activa si tiene commits propios y un árbol resultante diferente. Cada comando usa un timeout de 15 segundos, configurable mediante ODOO_GIT_TIMEOUT_MS.

Licencia

MIT