Odoo MCP Server

# Odoo MCP Server for Claude 🤖 **Servidor MCP (Model Context Protocol) para integrar Odoo con Claude AI** Este servidor expone herramientas de análisis de ventas, clientes y CRM de Odoo para que Claude pueda acceder y analizar datos empresariales en tiempo real. ## 📋 Características ### Herramientas Disponibles 1. **📊 Sales Data** - Obtener datos de ventas con filtros avanzados 2. **👥 Customer Insights** - Análisis RFM y segmentación de clientes (VIP, At Risk, New, etc.) 3. **🎯 CRM Opportunities** - Análisis del pipeline de ventas 4. **📦 Product Performance** - Rendimiento y ranking de productos 5. **👨‍💼 Sales Team Performance** - Métricas del equipo comercial 6. **🔍 Customer Search** - Búsqueda rápida de clientes 7. **🗺️ Territorial Analysis** - Análisis territorial por provincia/ciudad (ventas, clientes, productos por zona) 8. **📈 Comprehensive Data** - Análisis completo en una sola llamada ### Segmentación de Clientes (RFM) El servidor implementa análisis RFM automático: - **VIP**: Alta facturación (>€10k) y frecuencia (>5 compras) - **At Risk**: Clientes recurrentes sin compras en 180+ días - **New**: Primera compra en los últimos 30 días - **Inactive**: Sin compras en más de 365 días - **Regular**: Resto de clientes activos ### Análisis Territorial Exhaustivo (v1.2.0) Análisis territorial avanzado con múltiples dimensiones de inteligencia de negocio: **📊 Métricas por Provincia:** - Total de ventas y número de pedidos - Número de clientes activos y ciudades cubiertas - Ticket promedio por zona - Top 5 ciudades con más ventas **👥 Segmentación RFM por Territorio:** - Distribución de clientes VIP, At Risk, New, Regular e Inactive - Análisis de calidad de cartera por provincia - Identificación de territorios con alto valor de cliente **📈 Análisis Temporal (MoM):** - Comparación con período anterior equivalente - Tasa de crecimiento por provincia - Identificación de tendencias territoriales - Top provincias en crecimiento **📍 Métricas de Concentración:** - Porcentaje de concentración en top 3 ciudades - Índice de diversificación territorial - Identificación de mercados concentrados vs distribuidos **💡 Oportunidades de Expansión:** - Ciudades con 1-2 clientes (potencial de crecimiento) - Territorios subatendidos (<5 clientes) - Análisis de cobertura y penetración de mercado **🎯 Análisis por Ciudad:** - Ingresos por ciudad dentro de cada provincia - Número de clientes y pedidos por ciudad - Identificación de zonas de alto rendimiento **📦 Productos por Territorio:** - Top 5 productos más vendidos en cada provincia - Cantidad y facturación por producto y zona - Identificación de preferencias regionales **👨‍💼 Cobertura de Vendedores:** - Vendedores activos por provincia - Facturación y número de deals por vendedor y zona - Análisis de cobertura territorial ## 🚀 Instalación y Configuración ### Requisitos Previos - Docker y Docker Compose instalados - Acceso a una instancia de Odoo (v14+) - API Key de Odoo (generar en: Preferencias > Seguridad > API Keys) ### Paso 1: Configurar Variables de Entorno ```bash # Copiar el archivo de ejemplo cp .env.example .env # Editar con tus credenciales nano .env ``` **Contenido del archivo `.env`:** ```bash ODOO_URL=http://tu-instancia.odoo.com/ ODOO_DB=tu-database-name ODOO_USERNAME=integracion@tuempresa.com ODOO_API_KEY=tu-api-key-de-odoo ``` ### Paso 2: Construir y Ejecutar ```bash # Construir la imagen Docker docker-compose build # Iniciar el contenedor docker-compose up -d # Verificar el estado docker-compose ps # Ver logs docker-compose logs -f ``` ### Paso 3: Verificar Instalación ```bash # Health check curl http://localhost:8000/health # Ver herramientas disponibles curl http://localhost:8000/tools # Documentación interactiva (Swagger) # Abrir en navegador: http://localhost:8000/docs ``` ## 📖 Uso con Claude ### Configurar en Claude Code Agregar el servidor MCP a tu configuración de Claude Code (`.claude/settings.json` o MCP config): ```json { "mcpServers": { "odoo": { "url": "http://localhost:8000", "transport": "http" } } } ``` ### Ejemplos de Prompts para Claude **Análisis de Ventas:** ``` "Muéstrame las ventas de los últimos 30 días" "Dame un análisis completo de rendimiento del equipo de ventas" "¿Cuáles son los 10 productos más vendidos este trimestre?" ``` **Gestión de Clientes:** ``` "¿Qué clientes están en riesgo de perderse?" "Muéstrame los clientes VIP por provincia" "Busca clientes que contengan 'García' en su nombre" ``` **Pipeline y Oportunidades:** ``` "Analiza el pipeline de oportunidades con probabilidad mayor al 50%" "¿Cuáles son las oportunidades más grandes del mes?" ``` **Análisis Territorial Avanzado (v1.2.0):** ``` "Dame un análisis territorial exhaustivo de los últimos 30 días" "¿Qué provincias están creciendo más rápido?" "Muéstrame qué ciudades tienen potencial de expansión" "¿Cuáles provincias tienen más clientes VIP?" "Identifica territorios con alta concentración de ventas" "¿Dónde están los clientes en riesgo por provincia?" "Compara el crecimiento territorial del mes actual vs anterior" "¿Qué productos se venden más en cada provincia?" "Muéstrame oportunidades de expansión territorial" ``` ## 🔧 Comandos Útiles ### Gestión del Contenedor ```bash # Ver logs en tiempo real docker-compose logs -f odoo-mcp # Reiniciar el servicio docker-compose restart # Detener el servicio docker-compose down # Reconstruir después de cambios en el código docker-compose down docker-compose build --no-cache docker-compose up -d # Ver estadísticas de recursos docker stats odoo-mcp-server ``` ### Desarrollo ```bash # Ejecutar tests (dentro del contenedor) docker exec -it odoo-mcp-server python -m pytest # Acceder a shell del contenedor docker exec -it odoo-mcp-server bash # Ver variables de entorno docker exec odoo-mcp-server env | grep ODOO ``` ## 📊 Endpoints de la API | Endpoint | Método | Descripción | |----------|--------|-------------| | `/` | GET | Información del servidor | | `/health` | GET | Health check + estado conexión Odoo | | `/tools` | GET | Lista de herramientas disponibles | | `/get_sales_data` | POST | Datos de ventas con filtros | | `/get_customer_insights` | POST | Segmentación RFM de clientes | | `/get_crm_opportunities` | POST | Análisis del pipeline CRM | | `/get_product_performance` | POST | Ranking de productos | | `/get_sales_team_performance` | POST | Métricas del equipo | | `/search_customers` | POST | Búsqueda de clientes | | `/get_territorial_analysis` | POST | Análisis por provincia/ciudad | | `/get_comprehensive_data` | POST | Análisis completo | ## 🔒 Seguridad ### Recomendaciones 1. **API Key**: Usa un usuario de integración dedicado en Odoo con permisos limitados 2. **Network**: En producción, usa una red Docker privada 3. **HTTPS**: Configura un reverse proxy (Nginx/Traefik) con SSL 4. **Firewall**: Limita el acceso al puerto 8000 solo desde localhost o IPs autorizadas ### Permisos Necesarios en Odoo El usuario de integración debe tener acceso a: - Ventas (`sale.order`) - Clientes (`res.partner`) - CRM (`crm.lead`) - Productos (`product.product`, `sale.order.line`) ## 🐛 Troubleshooting ### Error: "Authentication failed" ```bash # Verificar credenciales docker logs odoo-mcp-server | grep -i auth # Comprobar que ODOO_API_KEY es válida en Odoo UI # Regenerar API Key si es necesario ``` ### Error: "Connection refused" ```bash # Verificar que Odoo está accesible curl -I http://tu-instancia.odoo.com/ # Verificar red Docker docker network inspect odoo-mcp-server_odoo-network ``` ### El contenedor no arranca ```bash # Ver logs completos docker-compose logs odoo-mcp # Verificar sintaxis del .env cat .env # Rebuild completo docker-compose down -v docker-compose build --no-cache docker-compose up ``` ### Health check falla ```bash # Verificar salud manualmente docker exec odoo-mcp-server curl -f http://localhost:8000/health # Ver logs del health check docker inspect odoo-mcp-server | jq '.[0].State.Health' ``` ## 📦 Estructura del Proyecto ``` odoo-mcp-server/ ├── odoo_mcp_api.py # Código principal FastAPI + lógica MCP ├── requirements.txt # Dependencias Python ├── Dockerfile # Configuración Docker ├── docker-compose.yml # Orquestación Docker ├── .env.example # Template de variables de entorno ├── .gitignore # Archivos a ignorar en Git └── README.md # Esta documentación ``` ## 🔄 Actualización ```bash # Pull últimos cambios git pull # Rebuild y restart docker-compose down docker-compose build --no-cache docker-compose up -d # Verificar versión curl http://localhost:8000/ | jq '.version' ``` ## 📝 Changelog ### v1.2.0 (Actual) - Análisis Territorial Exhaustivo - 🚀 **NUEVO**: Segmentación RFM por territorio - Distribución de clientes VIP, At Risk, New, Regular e Inactive por provincia - Análisis de calidad de cartera territorial - Métricas globales de segmentación agregadas - 📈 **NUEVO**: Análisis temporal period-over-period - Comparación automática con período anterior (MoM) - Tasa de crecimiento por provincia - Top provincias en crecimiento - Métricas globales de crecimiento - 📊 **NUEVO**: Métricas de concentración de mercado - Porcentaje de concentración en top 3 ciudades - Identificación de mercados concentrados (>80%) - Total de ciudades por provincia - 💡 **NUEVO**: Análisis de oportunidades de expansión - Ciudades con 1-2 clientes para potencial crecimiento - Territorios subatendidos (<5 clientes) - Identificación de zonas de alto potencial - ✅ Datos territoriales incluidos en `/get_comprehensive_data` - ✅ Backward compatible con v1.1.0 ### v1.1.0 - 🗺️ **NUEVO**: Análisis territorial por provincia/ciudad - Agregación de ventas, clientes y productos por zona geográfica - Top ciudades por provincia con métricas de rendimiento - Análisis de productos más vendidos por territorio - Cobertura de vendedores por zona - ✅ Datos geográficos completos en customer insights y búsqueda - ✅ Documentación mejorada de configuración `.env` ### v1.0.1 - ✅ Fix: Manejo correcto de `product_id` nulos en rendimiento de productos - ✅ Implementación de segmentación RFM avanzada - ✅ Health check mejorado con estado de conexión Odoo - ✅ Logging estructurado con emojis ### v1.0.0 - 🎉 Release inicial - 📊 7 herramientas MCP implementadas - 🔐 Autenticación XML-RPC con API Key - 🏥 Health checks automáticos ## 🤝 Contribución Para contribuir al proyecto: 1. Fork el repositorio 2. Crea una rama para tu feature (`git checkout -b feature/nueva-herramienta`) 3. Commit tus cambios (`git commit -am 'Añade nueva herramienta'`) 4. Push a la rama (`git push origin feature/nueva-herramienta`) 5. Abre un Pull Request ## 📄 Licencia Este proyecto es de código abierto y está disponible bajo la licencia MIT. ## 🆘 Soporte Si encuentras problemas: 1. Revisa la sección de **Troubleshooting** 2. Consulta los logs: `docker-compose logs -f` 3. Verifica el health endpoint: `curl http://localhost:8000/health` 4. Abre un issue en el repositorio del proyecto --- **Desarrollado para integración con Claude AI** 🤖