Odoo Projects

Servidor MCP remoto que da a Claude acceso al módulo de Proyectos de Odoo (Odoo Online / SaaS Custom), pensado para que varios miembros de un equipo lo usen, cada uno con su propia identidad de Odoo.

• CRUD completo sobre proyectos, tareas, etapas, partes de horas (timesheets) e hitos, incluido el borrado.
• Autenticación por persona mediante token en la URL: cada usuario tiene una URL propia (https://<dominio>/mcp/<token>). El servidor mapea cada token a un login + API key de Odoo. Así cada acción queda registrada bajo el usuario real y respeta sus permisos de Odoo, sin que la API key viaje nunca en la URL. (Se usa este método porque el conector de Claude no reenvía cabeceras HTTP personalizadas; la URL sí llega siempre intacta.)
• Auto-registro (self-service): los usuarios se dan de alta solos en la página /enroll con una clave de invitación. El servidor valida sus credenciales contra Odoo y guarda el mapa en un volumen persistente. El administrador no tiene que editar variables ni redesplegar por cada persona.
• Desplegable en un VPS con Easypanel (que además gestiona el dominio y el certificado HTTPS automáticamente).

---

1. Requisitos previos

• Odoo Online con plan Custom (los planes One App Free y Standard no permiten la API externa).
• Un VPS con Easypanel instalado y un dominio (o subdominio) apuntando a él.
• Cada miembro del equipo necesita una cuenta de usuario en Odoo con acceso al módulo de Proyectos.

Nota de compatibilidad: el servidor usa la API externa XML-RPC (/xmlrpc/2). Odoo tiene previsto retirarla en favor de la nueva External JSON-2 API (Online 21.1, invierno 2027). Toda la comunicación con Odoo está aislada en la clase OdooClient de server.py para poder migrar sin tocar las herramientas.

---

2. Preparar Odoo (una vez, más una API key por persona)

2.1 Fijar contraseña a los usuarios (solo Odoo Online)

En Odoo Online los usuarios se crean sin contraseña local. Para poder generar una API key, cada usuario debe primero establecer una contraseña en su cuenta (Ajustes → Usuarios → seleccionar usuario → Cambiar contraseña).

2.2 Cada miembro genera su API key personal

Cada persona, con su propia sesión de Odoo:

1. Clic en su avatar (arriba a la derecha) → Mi perfil (o Preferencias).
2. Pestaña Seguridad de la cuenta.
3. Nueva clave de API → escribe una descripción (p. ej. "Claude MCP") → Generar clave.
4. Copia la clave en ese momento (no se vuelve a mostrar).

Cada quien guardará su par login + API key para el paso 4.

Seguridad: los permisos reales los define el rol del usuario en Odoo. Si quieres limitar a alguien a solo lectura, ajústalo en su perfil de Odoo (grupos de acceso), no en el MCP.

---

3. Desplegar en Easypanel

Tienes dos formas; la de App desde repositorio Git es la más cómoda si subes esta carpeta a GitHub/GitLab.

Opción A — desde repositorio Git (recomendada)

1. Sube esta carpeta (odoo-projects-mcp/) a un repositorio.
2. En Easypanel: Create → App.
3. Source: conecta tu repositorio y rama.
4. Build: selecciona Dockerfile (Easypanel lo detecta solo).
5. Environment: añade las variables (ver sección 3.1).
6. Domains: añade un dominio, p. ej. odoo-mcp.tudominio.com, con el puerto 8000. Easypanel emite el certificado HTTPS con Let's Encrypt automáticamente.
7. Deploy.

Opción B — imagen Docker manual

Si prefieres construir la imagen tú mismo:

docker build -t odoo-projects-mcp .
docker run -p 8000:8000 --env-file .env odoo-projects-mcp

Luego expón el contenedor con un dominio en Easypanel apuntando al puerto 8000.

3.1 Variables de entorno (en Easypanel → Environment)

Variable	Valor	Obligatoria
ODOO_URL	https://tuempresa.odoo.com (sin barra final)	Sí
ODOO_DB	nombre de la base de datos (suele ser el subdominio)	Sí
ENROLL_SECRET	clave de invitación para el auto-registro en /enroll	Sí (para self-service)
ODOO_USERS_FILE	/data/users.json (debe estar en un volumen persistente)	Sí (para self-service)
PUBLIC_BASE_URL	https://odoo-mcp.tudominio.com (para armar el enlace personal)	Recomendada
ODOO_USERS	mapa token|login|api_key (opcional, para sembrar usuarios manualmente)	No
MCP_PATH	/mcp (por defecto; normalmente no cambiar)	No
PORT	8000	No

Ver .env.example para el detalle.

3.2 Añadir el volumen persistente (una sola vez)

Para que los usuarios auto-registrados sobrevivan a reinicios y redeploys, monta un volumen:

1. En Easypanel → tu servicio → Mounts / Volúmenes → Add Volume.
2. Tipo Volume, con un nombre (p. ej. odoo-mcp-data) y Mount Path = /data.
3. Guarda y redepliega.

Así el archivo /data/users.json (donde se guardan los registros) persiste siempre.

3.3 Comprobar que arrancó

Abre en el navegador https://odoo-mcp.tudominio.com/enroll: debe aparecer el formulario de alta. En los logs de Easypanel verás Application startup complete.

---

4. Cómo se da de alta y conecta cada miembro del equipo

Con el auto-registro, tú (admin) solo compartes dos cosas con tu equipo: la URL /enroll y la clave de invitación (ENROLL_SECRET). Cada persona hace:

1. Genera su API key en Odoo: su avatar → Mi perfil → Seguridad de la cuenta → Nueva clave de API → copia la clave. (En Odoo Online, antes debe tener una contraseña establecida en su usuario.)
2. Se registra: abre https://odoo-mcp.tudominio.com/enroll, escribe la clave de invitación, su correo de Odoo y su API key, y pulsa Generar mi enlace.
3. El servidor valida contra Odoo y le muestra su URL personal, tipo https://odoo-mcp.tudominio.com/mcp/<su-token>.
4. Conecta en Claude: Ajustes → Conectores → Añadir conector personalizado → pega esa URL como URL del conector → Guardar.

Listo: a partir de ahí Claude actúa en Odoo como esa persona, sin cabeceras ni credenciales dentro de Claude.

Revocar acceso: borra la entrada del usuario en /data/users.json (o su API key en Odoo). Cambiar ENROLL_SECRET impide nuevos registros pero no afecta a los ya dados de alta.

---

5. Módulos y nivel de acceso

Los permisos efectivos siempre están limitados por el rol del usuario de Odoo. Además, el propio servidor solo expone estas capacidades:

Módulo	Acceso	Herramientas
Proyectos	Lectura + escritura + borrado	list_projects, get_project, list_tasks, get_task, list_stages, my_tasks, list_timesheets, list_milestones, create_task, update_task, move_task_stage, create_project, log_timesheet, create_milestone, delete_task, delete_project
CRM	Lectura + escritura	list_leads, get_lead, create_lead, update_lead, move_lead_stage, list_crm_stages, list_crm_teams
Soporte / Helpdesk ⁽¹⁾	Lectura + escritura	list_tickets, get_ticket, create_ticket, update_ticket, move_ticket_stage, list_helpdesk_teams, list_helpdesk_stages
Email Marketing	Lectura + escritura ⁽²⁾	list_mailings, get_mailing, create_mailing_draft, list_mailing_lists, list_mailing_contacts, add_mailing_contact
Automatización de Marketing ⁽¹⁾	Lectura + escritura	list_marketing_campaigns, get_marketing_campaign, list_marketing_activities, set_marketing_campaign_state
Tableros / Dashboards	Solo lectura	list_dashboard_groups, list_dashboards
Ventas	Solo lectura	list_sales_orders, get_sales_order
Contabilidad	Solo lectura	list_invoices, get_invoice
Compras	Solo lectura	list_purchase_orders, get_purchase_order
Gastos	Solo lectura	list_expenses, get_expense
Utilidades	Lectura	find_users, find_partners

⁽¹⁾ Helpdesk y Marketing Automation son apps de Odoo Enterprise; si no están instaladas, esas herramientas devolverán un error claro. ⁽²⁾ create_mailing_draft crea el envío en borrador: el envío real se confirma manualmente desde Odoo (no se envían correos automáticamente).

Los módulos en solo lectura (Ventas, Contabilidad, Compras, Gastos) no exponen ninguna herramienta de crear/editar/borrar por diseño.

Ejemplos de cosas que le puedes pedir a Claude:

• "¿Qué oportunidades abiertas tengo en el CRM por etapa?"
• "Crea un ticket de soporte para el cliente X sobre un problema de facturación."
• "¿Cuánto suman las facturas de cliente pendientes de pago este mes?" (solo lectura)
• "Muéstrame los contactos de la lista de email marketing 'Newsletter'."
• "Crea una tarea 'Revisar contrato' en el proyecto Alfa, asignada a María, para el viernes."

---

6. Notas de seguridad

• Cifrado en reposo: define MASTER_KEY (clave Fernet) para que el archivo de usuarios se guarde cifrado. Sin ella, se guarda en texto plano (solo para pruebas). Genera la clave con python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" y guárdala fuera del repo.
• Cifrado en tránsito: sirve el MCP siempre por HTTPS (Easypanel lo hace por defecto).
• La API key nunca va en la URL; el servidor la resuelve desde el token. Aun así, la URL personal es un secreto: quien la tenga actúa como ese usuario.
• Rotación / caducidad: con TOKEN_TTL_DAYS los enlaces caducan; re-registrarse invalida automáticamente el token anterior del mismo usuario.
• Rate limiting por IP en /enroll (anti fuerza bruta) y en el endpoint MCP (ENROLL_RATELIMIT, MCP_RATELIMIT).
• Sin tokens en logs: el access-log de uvicorn está desactivado para que los tokens (en la URL) no queden registrados. Recomendado: desactiva también el access-log del proxy (Traefik/Easypanel) o excluye el path /mcp.
• Borrado protegido: delete_* requiere ALLOW_DELETE=true y confirm=true (mitiga borrados accidentales y prompt-injection). Por defecto, deshabilitado.
• Permisos por usuario: los permisos efectivos son los del usuario de Odoo (grupos/ACLs). Para restringir a alguien, ajusta su rol en Odoo.
• Revocar a una persona: borra su entrada en users.json (o su API key en Odoo). Cambiar ENROLL_SECRET bloquea nuevos registros.
• Una petición sin token o con token desconocido/caducado es rechazada: no hay acceso anónimo.
• Dependencias fijadas (requirements.txt con versiones exactas). Audita con pip-audit -r requirements.txt.

Responsabilidad del operador (fuera del código)

• Hardening del VPS que corre Easypanel: parcheo del SO, SSH con llaves, firewall, backups cifrados, acceso restringido al panel.
• Cumplimiento de datos: al usar este MCP, datos de Odoo (financieros, PII de clientes) se procesan en un LLM de terceros. Verifica el acuerdo de tratamiento de datos (DPA), la residencia/retención y la clasificación de datos permitida antes de un uso amplio o con datos regulados.