Skip to main content
Glama
Gerent365 MCP Server

Gerent365 MCP Server

Gerent365 MCP Server

Servidor MCP (Model Context Protocol) para Gerent365, el SaaS de gestión de restaurantes y negocios (Puerto Rico). Permite que asistentes de IA como Claude controlen toda tu cuenta de Gerent365 con lenguaje natural: empleados, horarios, nómina, propinas, fichaje (kiosko), clientes, productos, mesas, reservaciones, ausencias, asistencia, reportes y estadísticas.

El servidor se autentica automáticamente en https://app.gerent365.com/api (POST /auth/login) y mantiene la sesión mediante cookies durante toda la ejecución. Para las herramientas de kiosko usa kioskCode + pin.


Requisitos

  • Node.js 18 o superior (probado en Node 22).

  • Una cuenta de Gerent365 con rol admin, manager o superadmin para las operaciones de escritura.


Related MCP server: Adam OS MCP Server

Instalación

# 1. Clona o copia el proyecto y entra en la carpeta
cd gerent365-mcp

# 2. Instala las dependencias
npm install

# 3. Compila el TypeScript a JavaScript (genera dist/)
npm run build

Scripts disponibles:

Script

Acción

npm run build

Compila src/ a dist/ con tsc.

npm start

Ejecuta el servidor compilado (node dist/index.js).

npm run dev

Compila en modo watch (recompila al guardar).


Configuración (variables de entorno)

Copia .env.example a .env y completa tus datos. El servidor también lee las variables directamente del entorno (útil al configurarlo en un cliente MCP).

Variable

Obligatoria

Descripción

Default

GERENT365_EMAIL

Sí*

Email de tu cuenta de Gerent365.

—

GERENT365_PASSWORD

Sí*

Contraseña de tu cuenta.

—

GERENT365_API_URL

No

URL base de la API.

https://app.gerent365.com/api

GERENT365_KIOSK_CODE

No**

Código único de kiosko del negocio.

—

GERENT365_PIN

No**

PIN de fichaje del empleado.

—

GERENT365_MANAGER_CODE

No

Código de manager (autoriza fichajes tardíos).

—

* Obligatorias para las herramientas de dashboard (empleados, nómina, horarios, etc.). ** Obligatorias solo para las herramientas de kiosko/fichaje (o se pueden pasar como parámetros en cada llamada).

El servidor hace auto-login al arrancar. Si faltan GERENT365_EMAIL/GERENT365_PASSWORD, arranca igual pero solo funcionarán las herramientas de kiosko (o deberás usar gerent365_login manualmente).


Configuración en Claude Desktop

Edita el archivo de configuración de Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Añade el servidor (usa la ruta absoluta a dist/index.js):

{
  "mcpServers": {
    "gerent365": {
      "command": "node",
      "args": ["/ruta/absoluta/a/gerent365-mcp/dist/index.js"],
      "env": {
        "GERENT365_EMAIL": "admin@tunegocio.com",
        "GERENT365_PASSWORD": "tu_contrasena",
        "GERENT365_API_URL": "https://app.gerent365.com/api",
        "GERENT365_KIOSK_CODE": "KSK-0000",
        "GERENT365_PIN": "1234"
      }
    }
  }
}

Guarda el archivo y reinicia Claude Desktop. Verás las herramientas de Gerent365 disponibles (icono de herramientas 🔨).


Configuración en otros clientes MCP

El servidor habla MCP sobre stdio, por lo que funciona con cualquier cliente compatible (Cline, Continue, Zed, LibreChat, etc.). La idea es siempre la misma:

  • Comando: node

  • Argumentos: ["/ruta/absoluta/a/gerent365-mcp/dist/index.js"]

  • Variables de entorno: las de la tabla anterior.

Ejemplo genérico (formato tipo mcp.json):

{
  "servers": {
    "gerent365": {
      "type": "stdio",
      "command": "node",
      "args": ["/ruta/absoluta/a/gerent365-mcp/dist/index.js"],
      "env": {
        "GERENT365_EMAIL": "admin@tunegocio.com",
        "GERENT365_PASSWORD": "tu_contrasena"
      }
    }
  }
}

También puedes probarlo con el MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Herramientas disponibles (56)

Autenticación y perfil

Herramienta

Descripción

gerent365_login

Inicia sesión (email, password).

gerent365_logout

Cierra la sesión.

gerent365_get_profile

Perfil del usuario actual + negocio.

Negocio

Herramienta

Descripción

gerent365_get_business

Ver información del negocio.

gerent365_update_business

Actualizar negocio (nombre, email, teléfono, dirección, zona horaria, ajustes).

Empleados

Herramienta

Descripción

gerent365_list_employees

Listar empleados.

gerent365_get_employee

Ver empleado por ID.

gerent365_create_employee

Crear empleado.

gerent365_update_employee

Actualizar empleado.

gerent365_delete_employee

Eliminar empleado.

gerent365_update_employee_pin

Cambiar PIN de fichaje.

Puestos de trabajo

Herramienta

Descripción

gerent365_list_job_positions

Listar puestos.

gerent365_create_job_position

Crear puesto (tarifa por hora, color).

gerent365_update_job_position

Actualizar puesto.

gerent365_delete_job_position

Eliminar puesto.

Horarios

Herramienta

Descripción

gerent365_get_schedule

Ver horario de una semana.

gerent365_assign_shift

Asignar/actualizar turno.

gerent365_copy_week

Copiar semana de horarios.

gerent365_publish_schedule

Publicar horario de una semana.

gerent365_get_publish_status

Ver estado de publicación.

Nómina

Herramienta

Descripción

gerent365_list_payroll

Listar periodos de nómina.

gerent365_create_payroll_period

Crear periodo.

gerent365_calculate_payroll

Calcular nómina.

gerent365_approve_payroll

Aprobar periodo.

gerent365_pay_payroll

Marcar como pagado.

Propinas

Herramienta

Descripción

gerent365_list_tips

Listar pools de propinas.

gerent365_create_tip_pool

Crear pool de propinas.

gerent365_distribute_tips

Distribuir propinas.

Kiosko / Fichaje

Herramienta

Descripción

gerent365_kiosko_validate

Validar empleado (kioskCode + pin).

gerent365_kiosko_punch

Registrar fichaje (CHECK_IN/OUT, BREAK).

gerent365_kiosko_products

Ver productos desde kiosko.

Clientes

Herramienta

Descripción

gerent365_list_customers

Listar clientes.

gerent365_search_customers

Buscar clientes.

gerent365_create_customer

Crear cliente.

gerent365_update_customer

Actualizar cliente.

Productos y categorías

Herramienta

Descripción

gerent365_list_products

Listar productos.

gerent365_create_product

Crear producto.

gerent365_list_product_categories

Listar categorías.

gerent365_create_product_category

Crear categoría.

Mesas

Herramienta

Descripción

gerent365_list_tables

Listar mesas.

gerent365_create_table

Crear mesa.

gerent365_update_table

Actualizar mesa (número, capacidad, ubicación, estado, etc.).

gerent365_delete_table

Eliminar mesa.

Reservaciones

Herramienta

Descripción

gerent365_list_reservations

Listar reservaciones.

gerent365_create_reservation

Crear reservación.

gerent365_update_reservation

Actualizar reservación.

Ausencias

Herramienta

Descripción

gerent365_list_time_off

Listar solicitudes de ausencia.

gerent365_create_time_off

Crear solicitud de ausencia.

gerent365_update_time_off

Aprobar/rechazar solicitud.

gerent365_delete_time_off

Cancelar una solicitud (solo si sigue en estado PENDING).

Asistencia

Herramienta

Descripción

gerent365_get_attendance

Ver registros de asistencia.

gerent365_get_last_punch

Ver último fichaje de un empleado.

Reportes, dashboard y notificaciones

Herramienta

Descripción

gerent365_report_dashboard

Reporte del dashboard.

gerent365_report_sales

Reporte de ventas.

gerent365_dashboard_stats

Estadísticas del dashboard.

gerent365_get_notifications

Ver notificaciones.


Ejemplos de uso en lenguaje natural

Una vez configurado en Claude (o tu cliente MCP), puedes pedir cosas como:

  • "Muéstrame todos los empleados de mi restaurante."

  • "Crea un empleado llamado María López, mesera, con email maria@bar.com y PIN 4821."

  • "¿Cómo va el horario de la semana del 27 de julio? Publícalo cuando esté listo."

  • "Asigna a Juan un turno el lunes de 9:00 a 17:00 con descanso de 13:00 a 13:30."

  • "Copia el horario de esta semana a la próxima."

  • "Crea un periodo de nómina del 1 al 15 de julio incluyendo propinas de tarjeta, calcúlalo y muéstrame el total."

  • "Registra un pool de propinas de hoy con $200 en efectivo y $350 en tarjeta, y repártelo entre el equipo por horas trabajadas."

  • "Ficha mi entrada en el kiosko." (usa GERENT365_KIOSK_CODE y GERENT365_PIN).

  • "Busca al cliente con teléfono 787-555-1234 y márcalo como VIP."

  • "Crea una reservación para 4 personas mañana a las 8pm a nombre de Pedro."

  • "Dame las estadísticas del dashboard de hoy."


Notas técnicas

  • Autenticación en dos mundos: las rutas de dashboard usan sesión por cookie (login automático); las de kiosko usan kioskCode + pin.

  • Multi-tenant: el businessId se deriva de la sesión; nunca se pasa como parámetro.

  • Roles: la mayoría de operaciones de escritura requieren rol admin, manager o superadmin.

  • Fechas: usa formato ISO YYYY-MM-DD (y HH:mm para horas). Las comparaciones horarias usan la zona horaria del negocio (default America/Puerto_Rico).

  • Overtime: el backend de Gerent365 no calcula horas extra; la nómina es a tiempo simple.

  • Los errores de la API se devuelven con un mensaje claro en español, incluyendo el código HTTP.

  • Cobertura de pruebas (2026-08-09): las 54 herramientas fueron probadas en vivo contra cuentas reales en dos sesiones, incluida la cadena completa de nómina (create_payroll_period → calculate_payroll → approve_payroll → pay_payroll), reparto de propinas, publicación de horario y fichaje de kiosko. Ver historial de commits para el detalle de los bugs reales encontrados y corregidos en el proceso.


Estructura del proyecto

gerent365-mcp/
├── src/
│   ├── index.ts          # Entry point del servidor MCP
│   ├── auth.ts           # Manejo de sesión (login, cookies)
│   ├── client.ts         # HTTP client con cookie-jar
│   └── tools/
│       ├── types.ts      # Tipos y utilidades compartidas
│       ├── auth.ts       # Autenticación y perfil
│       ├── business.ts   # Negocio
│       ├── employees.ts  # Empleados y puestos
│       ├── schedules.ts  # Horarios
│       ├── payroll.ts    # Nómina
│       ├── tips.ts       # Propinas
│       ├── kiosko.ts     # Kiosko / fichaje
│       ├── customers.ts  # Clientes
│       ├── products.ts   # Productos y categorías
│       ├── tables.ts     # Mesas
│       ├── reservations.ts # Reservaciones
│       ├── timeoff.ts    # Ausencias
│       ├── attendance.ts # Asistencia
│       ├── reports.ts    # Reportes
│       └── dashboard.ts  # Estadísticas y notificaciones
├── package.json
├── tsconfig.json
├── README.md
└── .env.example

Licencia

PolyForm Shield 1.0.0 — uso libre para cualquier propósito, incluido comercial, excepto para crear un producto o servicio que compita con este. Ver LICENSE.

Available Tools

53 tools
gerent365_approve_payrollA

Aprueba un periodo de nómina previamente calculado.

Inputs: id (required).

gerent365_assign_shiftA

Asigna o actualiza un turno de un empleado en un día. Soporta jornada partida (startTime2/endTime2), descansos y marcar el día como libre (isOff).

Inputs: date (required), profileId (required), isOff, notes, +7 more.

gerent365_calculate_payrollA

Calcula la nómina de un periodo (horas trabajadas, propinas e impuestos de Puerto Rico). Solo aplica a periodos en estado DRAFT o CALCULATED.

Inputs: id (required).

gerent365_copy_weekB

Copia todos los turnos de una semana origen a una semana destino.

Inputs: sourceWeekStart (required), targetWeekStart (required).

gerent365_create_customerC

Crea un nuevo cliente.

Inputs: name (required), tags, email, isVip, +6 more.

gerent365_create_employeeC

Crea un nuevo empleado en el negocio.

Inputs: email (required), fullName (required), pin, role, +5 more.

gerent365_create_job_positionB

Crea un nuevo puesto de trabajo con tarifa por hora, color y departamento.

Inputs: name (required), color, department, hourlyRate, +1 more.

gerent365_create_payroll_periodC

Crea un nuevo periodo de nómina con rango de fechas y opciones de inclusión de propinas.

Inputs: endDate (required), startDate (required), notes, includeCardTips, +1 more.

gerent365_create_productC

Crea un nuevo producto con precio, categoría e impuestos.

Inputs: name (required), price (required), sku, cost, +7 more.

gerent365_create_product_categoryB

Crea una nueva categoría de productos.

Inputs: name (required), color, sortOrder, description.

gerent365_create_reservationC

Crea una nueva reservación.

Inputs: date (required), name (required), time (required), partySize (required), +4 more.

gerent365_create_tableB

Crea una nueva mesa con número, capacidad y ubicación.

Inputs: number (required), capacity (required), name, notes, +1 more.

gerent365_create_time_offB

Crea una solicitud de ausencia para un empleado.

Inputs: endDate (required), profileId (required), startDate (required), type, +1 more.

gerent365_create_tip_poolB

Crea un pool de propinas para una fecha, con montos en efectivo y tarjeta.

Inputs: date (required), notes, cardAmount, cashAmount.

gerent365_dashboard_statsB

Obtiene las estadísticas del dashboard del negocio (ventas, empleados, actividad, etc.).

Inputs: no named parameters.

gerent365_delete_employeeA

Elimina un empleado por su ID.

Inputs: id (required).

gerent365_delete_job_positionB

Elimina un puesto de trabajo por su ID.

Inputs: id (required).

gerent365_distribute_tipsA

Distribuye un pool de propinas entre empleados. Usa 'method' (p.ej. por horas trabajadas) y employeeIds, o distribuciones manuales.

Inputs: tipId (required), method, employeeIds, manualDistributions.

gerent365_get_attendanceA

Obtiene los registros de asistencia (fichajes). Se puede filtrar por empleado y rango de fechas.

Inputs: endDate, profileId, startDate.

gerent365_get_businessA

Obtiene la información del negocio del usuario autenticado (nombre, email, teléfono, dirección, zona horaria, ajustes, etc.).

Inputs: no named parameters.

gerent365_get_employeeA

Obtiene los datos de un empleado por su ID.

Inputs: id (required).

gerent365_get_last_punchB

Obtiene el último fichaje (punch) de un empleado.

Inputs: profileId.

gerent365_get_notificationsC

Obtiene las notificaciones del usuario/negocio.

Inputs: unreadOnly.

gerent365_get_profileA

Obtiene el perfil del usuario autenticado actualmente junto con la información de su negocio (endpoint /auth/me).

Inputs: no named parameters.

gerent365_get_publish_statusA

Consulta si el horario de una semana ya fue publicado.

Inputs: weekStart (required).

gerent365_get_scheduleB

Obtiene el horario de una semana. Recibe weekStart en formato YYYY-MM-DD (típicamente el lunes).

Inputs: weekStart (required).

gerent365_kiosko_productsA

Obtiene los productos disponibles desde el kiosko (autenticado con kioskCode + pin).

Inputs: pin, kioskCode.

gerent365_kiosko_punchA

Registra un fichaje (punch) en el kiosko: entrada, salida o descanso. Incluye coordenadas GPS opcionales. Si el fichaje es tardío puede requerir managerCode.

Inputs: type (required), pin, latitude, kioskCode, +3 more.

gerent365_kiosko_validateA

Valida un empleado en el kiosko con kioskCode + pin y devuelve su estado de fichaje y la siguiente acción disponible (CHECK_IN, CHECK_OUT, BREAK_START, BREAK_END).

Inputs: pin, kioskCode.

gerent365_list_customersA

Lista los clientes del negocio.

Inputs: no named parameters.

gerent365_list_employeesA

Lista todos los empleados del negocio.

Inputs: no named parameters.

gerent365_list_job_positionsA

Lista los puestos de trabajo (JobPosition) del negocio, con sus tarifas por hora.

Inputs: no named parameters.

gerent365_list_payrollA

Lista los periodos de nómina del negocio. Se puede filtrar por estado (DRAFT, CALCULATED, APPROVED, PAID).

Inputs: status.

gerent365_list_product_categoriesA

Lista las categorías de productos del negocio.

Inputs: no named parameters.

gerent365_list_productsA

Lista los productos del negocio.

Inputs: no named parameters.

gerent365_list_reservationsA

Lista las reservaciones del negocio. Se puede filtrar por fecha.

Inputs: date, status.

gerent365_list_tablesA

Lista las mesas del negocio.

Inputs: no named parameters.

gerent365_list_time_offA

Lista las solicitudes de ausencia. Se puede filtrar por estado.

Inputs: status.

gerent365_list_tipsA

Lista los pools de propinas (tip pools) del negocio.

Inputs: no named parameters.

gerent365_loginA

Inicia sesión en Gerent365 con email y contraseña. Guarda las cookies de sesión para las demás herramientas. Si no se pasan credenciales, usa las de las variables de entorno.

Inputs: email, password.

gerent365_logoutA

Cierra la sesión actual en Gerent365 y limpia las cookies almacenadas.

Inputs: no named parameters.

gerent365_pay_payrollB

Marca un periodo de nómina como pagado.

Inputs: id (required).

gerent365_publish_scheduleA

Publica el horario de una semana y notifica a los empleados activos.

Inputs: weekStart (required).

gerent365_report_dashboardB

Obtiene el reporte del dashboard (resumen de métricas). Acepta rango de fechas opcional.

Inputs: endDate, startDate.

gerent365_report_salesC

Obtiene el reporte de ventas del negocio para un rango de fechas.

Inputs: endDate, startDate.

gerent365_search_customersA

Busca clientes por texto (nombre, teléfono, email).

Inputs: q (required).

gerent365_update_businessB

Actualiza la información del negocio. Todos los campos son opcionales; solo se envían los provistos.

Inputs: name, email, phone, address, +5 more.

gerent365_update_customerB

Actualiza un cliente existente por su ID.

Inputs: id (required), name, tags, email, +7 more.

gerent365_update_employeeA

Actualiza los datos de un empleado existente. Solo se envían los campos provistos.

Inputs: id (required), role, email, phone, +5 more.

gerent365_update_employee_pinB

Cambia el PIN de fichaje (kiosko) de un empleado.

Inputs: id (required), pin (required).

gerent365_update_job_positionB

Actualiza un puesto de trabajo existente.

Inputs: id (required), name, color, isActive, +3 more.

gerent365_update_reservationB

Actualiza una reservación existente por su ID (fecha, hora, estado, etc.).

Inputs: id (required), date, name, time, +4 more.

gerent365_update_time_offB

Aprueba o rechaza una solicitud de ausencia (actualiza su estado).

Inputs: id (required), status, rejectionReason.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 53 tools

    Disambiguation3/5

    Several tools have overlapping purposes, such as list_customers vs search_customers, list_products vs kiosko_products, and report_dashboard vs dashboard_stats, which could cause misselection. However, most tools target distinct resources and actions, and descriptions provide enough context to differentiate them in most cases.

    Naming Consistency4/5

    Most tools follow a clear gerent365_verb_noun pattern (e.g., get_employee, list_payroll, create_reservation). A few deviations exist like kiosko_validate, kiosko_punch, kiosko_products, and dashboard_stats, which mix noun-first or noun-noun patterns, but these are minor and the overall convention is predictable.

    Tool Count2/5

    With 53 tools, the server feels overloaded, exceeding the 25+ threshold where tools become difficult to manage. While the domain is broad (HR, payroll, scheduling, kiosko, customers, products, reservations, reports), the high count makes it heavy and harder for an agent to navigate.

    Completeness3/5

    The tool set covers many core workflows (employee management, payroll lifecycle, scheduling, time off, attendance, reports). However, several resources lack full CRUD: products have no update/delete, reservations have no delete, and tables/categories only have create and list, leaving notable gaps in the surface.

    Related MCP Connectors

    Related MCP Servers