⏰ TimeZest MCP Server

Bringe deine TimeZest-Planungsdaten direkt in Claude über das Model Context Protocol (MCP). Führe Echtzeit-Terminabfragen, Techniker-Briefings und ticketbasiertes Terminmanagement durch – alles in natürlicher Sprache.

Registry ID: io.github.sagarkalra-tech/timezest-mcp

🌟 Warum TimeZest MCP?

Wenn du ein Team leitest, das TimeZest mit ConnectWise verwendet, kennst du das Problem: zwischen Tabs hin- und herwechseln, manuell prüfen, wer gebucht ist, ungebuchten Terminanfragen hinterherlaufen und Ticketnummern abgleichen.

Dieser MCP-Server macht Claude zu einem Terminplanungsassistenten, der Folgendes kann:

• 🗓️ dir eine Morgenübersicht der heutigen bestätigten Termine geben, gruppiert nach Techniker

• 🔍 Termine anhand der Ticketnummer finden – sag einfach „finde Termine für Ticket #964400"

• ⏳ ältere ungebuchte Anfragen aufspüren, die nachverfolgt werden müssen

• 📊 aggregierte Planungsstatistiken für dein Team erstellen

• 🕐 zeitzonengenaue Berichte für globale MSP-Teams erstellen

Related MCP server: AutotaskMCP

🚀 In 30 Sekunden loslegen

Voraussetzungen

• Node.js 20+ — Hier herunterladen

• TimeZest-API-Schlüssel — zu finden unter TimeZest → Einstellungen → API

Option 1: Claude Desktop (Empfohlen)

Füge dies zu deiner Claude-Desktop-Konfigurationsdatei hinzu:

• 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"
      }
    }
  }
}

Starte Claude Desktop neu. Fertig.

Option 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"
  }
}'

Option 3: VS Code (Copilot)

Füge dies zu deiner .vscode/settings.json oder zu deinen Benutzereinstellungen hinzu:

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

🛠️ Verfügbare Tools

Der Server stellt 8 spezialisierte Tools bereit, die Claude aufrufen kann:

💬 Beispiel-Prompts

Sobald die Verbindung steht, sprich einfach natürlich mit Claude:

"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?"

⚙️ Konfiguration

🏗️ Architektur

┌─────────────────────────────────────────────────────────────────┐
│                        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       │
└─────────────────────────────────────────────────────────────────┘

Wichtige Designentscheidungen

• Nur Lesezugriff: Bewusst schreibgeschützt – keine Änderungen an deinen Planungsdaten

• Robuster Client: Exponentieller Backoff mit automatischer Unterstützung des Retry-After-Headers bei 429/5xx-Fehlern

• Tiefe Pagination: Durchsucht rekursiv alle Seiten (in 50er-Schritten), um vollständige Datensätze zu erstellen

• Zeitzonen-Präzision: Konvertiert Unix-Zeitstempel in striktes ISO-Format mit lokalisierten Anzeigetexten unter Verwendung von IANA-Zeitzonenkennungen

• Techniker-Auflösung: Verwendet eine Suche mit „höchster Treffsicherheit“ – prüft zuerst scheduled_agents, fällt dann auf resources zurück

• Warm Cache: Termintypen werden nach dem ersten Abruf gecacht, um den API-Overhead zu reduzieren

🧪 Tests

Der Server wird mit einer umfassenden Vitest-Testsuite ausgeliefert – 22 Tests in 3 Dateien:

Alle Tests verwenden gemockte API-Antworten – keine Live-API-Aufrufe, keine Geheimnisse erforderlich.

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

🔒 Sicherheit & Vertrauen

• NPM-Provenienz: Jede Veröffentlichung wird über GitHub Actions OIDC kryptografisch signiert

• CI/CD-Pipeline: Automatisierter Build → Test → Publish bei getaggten Releases (kein manuelles npm publish)

• Keine Geheimnisse in CI: Tests benötigen keine API-Schlüssel – vollständig deterministisch mit gemockten Antworten

• Node.js-Matrix: Getestet mit Node 20 (LTS) und 22 (Current)

📦 Verteilung

🤝 Mitwirken

1. Forke das Repository

2. Erstelle einen Feature-Branch (git checkout -b feat/my-feature)

3. Nimm deine Änderungen vor und stelle sicher, dass die Tests bestehen (npm test)

4. Reiche einen Pull Request ein

Eine ausführliche Erläuterung des Datenflusses, des Komponentendesigns und der Transformationslogik findest du in ARCHITECTURE.md.

📄 Lizenz

MIT © 2026 Sagar Kalra