redbus-mcp

Servidor MCP (Model Context Protocol) para consultar pasajes de bus interprovinciales en Perú a través de redbus.pe. Permite que asistentes de IA compatibles con MCP (Cursor, VS Code, etc.) busquen buses en lenguaje natural: "buses de Lima a Arequipa el 20 de julio".

Alcance: solo consulta (lectura). No reserva ni realiza pagos.

Herramientas expuestas

Herramienta	Qué hace
buscar_ciudades	Busca ciudades/terminales por nombre y devuelve su ID (ej. Lima = 195105).
buscar_buses	Lista buses de una ruta y fecha: empresa, tipo, horarios, duración, precios, asientos disponibles, calificación, embarque/descenso y amenidades. Acepta nombres o IDs de ciudad.
detalle_servicio	Detalle de un servicio: mapa de asientos (número, tipo, precio, disponibilidad, piso) y puntos de embarque/descenso con horas y direcciones.

Requisitos

• Node.js ≥ 18 (probado en Node 22).

Instalación

npm install
npm run build

Verificación

Prueba end-to-end contra la API real de RedBus (sin capa MCP):

npm run smoke            # usa una fecha 3 días en el futuro
npm run smoke 2026-08-05 # o una fecha concreta (ISO yyyy-MM-dd)

Inspección interactiva del servidor MCP:

npm run inspector        # abre el MCP Inspector

Uso en un cliente MCP

Registra el servidor en la configuración MCP de tu cliente (el formato mcpServers es común a la mayoría). Ejemplo:

{
  "mcpServers": {
    "redbus-peru": {
      "command": "node",
      "args": ["C:\\Users\\paranda\\Documents\\Proyectos-personales\\redbus-mcp\\build\\index.js"]
    }
  }
}

Reinicia el cliente y pregunta, por ejemplo: "¿Qué buses hay de Lima a Cusco el 2026-07-20? Ordénalos por precio."

En Cursor / VS Code la configuración es equivalente (mcp.json / settings del cliente), apuntando command/args al mismo build/index.js.

Fechas

• Entrada del usuario: ISO yyyy-MM-dd (ej. 2026-07-20).
• Internamente el cliente convierte al formato que exige cada endpoint de RedBus (dd-MMM-yyyy para la búsqueda, ISO para el layout de asientos).
• La fecha debe ser hoy o futura; RedBus suele vender con pocas semanas de anticipación.

Cómo funciona (arquitectura)

RedBus expone una API interna en https://www.redbus.pe/rpw/api/. Un fetch plano es rechazado (protección anti-bot), por lo que src/redbusClient.ts:

1. Envía headers realistas de Chrome (User-Agent, Referer, Accept-Language: es-PE, etc.).
2. Hace warm-up: visita la home para obtener cookies y las reenvía en cada llamada.
3. Reintenta con backoff y re-hace el warm-up si detecta bloqueo (403/429/reset).
4. Aplica un rate-limit suave entre peticiones.

Toda la lógica anti-bot está aislada en redbusClient.ts: si RedBus endurece la protección, se puede migrar ese módulo a un navegador headless (Playwright) sin tocar las herramientas.

Estructura

src/
  index.ts            # arranque del servidor MCP (stdio) + registro de tools
  redbusClient.ts     # cliente HTTP: cookies, headers, warm-up, reintentos, endpoints
  types.ts            # tipos de las respuestas de RedBus
  tools/              # buscar_ciudades, buscar_buses, detalle_servicio
  lib/                # fechas, normalización de datos, catálogo de amenidades

Aviso

Este proyecto consume una API interna no pública de RedBus con fines personales y educativos. Respeta sus términos de servicio y evita un uso intensivo (ya incluye un rate-limit suave). No está afiliado a RedBus.

Licencia

MIT