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: Workadu 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:

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).

* 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 (54)

Autenticación y perfil

Negocio

Empleados

Puestos de trabajo

Horarios

Nómina

Propinas

Kiosko / Fichaje

Clientes

Productos y categorías

Mesas

Reservaciones

Ausencias

Asistencia

Reportes, dashboard y 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.