⏰ TimeZest MCP Server

Lleva tus datos de programación de TimeZest directamente a Claude a través del Protocolo de Contexto de Modelo (MCP). Realiza consultas de citas en tiempo real, resúmenes para ingenieros y gestión de horarios vinculados a tickets, todo con lenguaje natural.

ID de registro: io.github.sagarkalra-tech/timezest-mcp

🌟 ¿Por qué TimeZest MCP?

Si gestionas un equipo que usa TimeZest con ConnectWise, conoces el problema: cambiar entre pestañas, comprobar manualmente quién está reservado, perseguir solicitudes de programación sin reservar y cruzar números de ticket.

Este servidor MCP convierte a Claude en un asistente de programación que puede:

• 🗓️ Darte un resumen matutino de las citas confirmadas de hoy agrupadas por ingeniero

• 🔍 Encontrar citas por número de ticket — solo di "busca citas para el ticket #964400"

• ⏳ Mostrar solicitudes sin reservar que envejecen y necesitan seguimiento

• 📊 Generar estadísticas agregadas de programación en todo tu equipo

• 🕐 Manejar informes precisos en cuanto a zona horaria para equipos MSP globales

Related MCP server: Autotask MCP Server

🚀 Comienza en 30 segundos

Requisitos previos

• Node.js 20+ — Descargar aquí

• Clave de API de TimeZest — Se encuentra en TimeZest → Configuración → API

Opción 1: Claude Desktop (Recomendado)

Añade esto a tu archivo de configuración de Claude Desktop:

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

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

{
  "mcpServers": {
    "timezest": {
      "command": "npx",
      "args": ["-y", "timezest-mcp@latest"],
      "env": {
        "TIMEZEST_API_KEY": "your-timezest-api-key-here"
      }
    }
  }
}

Reinicia Claude Desktop. Ya está.

Opción 2: Claude Code CLI

claude mcp add-json timezest-mcp '{
  "command": "npx",
  "args": ["-y", "timezest-mcp@latest"],
  "env": {
    "TIMEZEST_API_KEY": "your-timezest-api-key-here"
  }
}'

Opción 3: VS Code (Copilot)

Añade a tu .vscode/settings.json o Configuración de Usuario:

{
  "mcp": {
    "servers": {
      "timezest": {
        "command": "npx",
        "args": ["-y", "timezest-mcp@latest"],
        "env": {
          "TIMEZEST_API_KEY": "your-timezest-api-key-here"
        }
      }
    }
  }
}

🛠️ Herramientas disponibles

El servidor expone 8 herramientas especializadas que Claude puede llamar:

💬 Ejemplos de prompts

Una vez conectado, simplemente habla con Claude de forma natural:

"Who are my top engineers today and what are they booked for?"

"Find any TimeZest requests for ticket #964400."

"Give me a morning briefing of today's confirmed vs. unbooked requests."

"Show me all pending scheduling requests older than 48 hours."

"What's the scheduling volume breakdown for the last two weeks?"

"Pull up Sarah's schedule for the next 5 days."

"List all cancelled appointments from last week — any we should rebook?"

⚙️ Configuración

🏗️ Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                        MCP CLIENT (Claude)                      │
│        Desktop App  •  Claude Code CLI  •  IDE Plugin           │
└──────────────────────────┬──────────────────────────────────────┘
                           │ Stdio (JSON-RPC)
┌──────────────────────────▼──────────────────────────────────────┐
│                     TIMEZEST MCP SERVER                         │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐                             │
│  │ Tool Handler │  │  MCP SDK     │  (index.ts)                 │
│  │ (8 Tools)    │  │  Registry    │                             │
│  └──────┬───────┘  └──────────────┘                             │
│         │                                                       │
│  ┌──────▼────────────────────────────────────────────────────┐  │
│  │                 TIMEZEST API CLIENT                        │  │
│  │  Pagination • Retry Logic • Rate Limit Management         │  │
│  └──────────────────────┬────────────────────────────────────┘  │
│                         │ (client.ts)                            │
│  ┌──────────────────────▼────────────────────────────────────┐  │
│  │               DATA TRANSFORMATION LAYER                    │  │
│  │  Timezone Math • Engineer Mapping • Ticket Linking         │  │
│  └────────────────────────────────────────────────────────────┘  │
│                         │ (utils/)                               │
└─────────────────────────┼────────────────────────────────────────┘
                          │ HTTPS / REST
┌─────────────────────────▼──────────────────────────────────────┐
│                      TIMEZEST API (v1)                          │
│       Scheduling Requests • Appointment Types • Resources       │
└─────────────────────────────────────────────────────────────────┘

Decisiones clave de diseño

• Solo lectura: Intencionalmente de solo lectura: sin mutaciones en tus datos de programación

• Cliente resiliente: Reintento exponencial con soporte automático del encabezado Retry-After para errores 429/5xx

• Paginación profunda: Recorre recursivamente todas las páginas (fragmentos de 50 elementos) para construir conjuntos de datos completos

• Precisión de zona horaria: Convierte marcas de tiempo Unix a ISO estricto con cadenas de visualización localizadas usando identificadores de zona horaria IANA

• Resolución de ingeniero: Utiliza una búsqueda de "mayor confianza": primero verifica scheduled_agents y luego recurre a resources

• Caché cálida: Los tipos de cita se almacenan en caché después de la primera consulta para reducir la sobrecarga de la API

🧪 Pruebas

El servidor incluye un conjunto de pruebas completo de Vitest — 22 pruebas en 3 archivos:

Todas las pruebas usan respuestas de API simuladas — sin llamadas API en vivo, sin necesidad de secretos.

npm test            # Single run
npm run test:watch  # Re-runs on file save

🔒 Seguridad y confianza

• Procedencia NPM: Cada versión está firmada criptográficamente mediante OIDC de GitHub Actions

• Pipeline CI/CD: Compilación → prueba → publicación automatizadas en versiones etiquetadas (sin npm publish manual)

• Sin secretos en CI: Las pruebas no requieren claves de API — completamente deterministas con respuestas simuladas

• Matriz de Node.js: Probado en Node 20 (LTS) y 22 (Actual)

📦 Distribución

🤝 Contribuciones

1. Haz un fork del repositorio

2. Crea una rama de características (git checkout -b feat/my-feature)

3. Haz tus cambios y asegúrate de que las pruebas pasen (npm test)

4. Envía una solicitud de extracción

Consulta ARCHITECTURE.md para una inmersión profunda en el flujo de datos, el diseño de componentes y la lógica de transformación.

📄 Licencia

MIT © 2026 Sagar Kalra