RepairDesk MCP Server

Ein MCP (Model Context Protocol) Server, der jedem MCP-kompatiblen KI-Assistenten – Claude Code, Claude Desktop, Codex CLI, OpenCode, Cursor, Windsurf oder jedem anderen MCP-Client – direkten Lese-/Schreibzugriff auf deine RepairDesk-Shop-Daten gibt. Richte ihn mit dem API-Schlüssel deines Shops ein und stelle Fragen wie „Ticket T-15423 nachschlagen", „Was ist auf Rechnung 8821 überfällig?" oder „Weise den iPhone-Screen-Job Dave zu".

Kein offizielles RepairDesk-Produkt – ein unabhängiges Tool, das von einem RepairDesk-Shop für RepairDesk-Shops entwickelt wurde. Keine Garantie, Nutzung auf eigenes Risiko (siehe Lizenz) – aber es wird täglich für die Ticket-Warteschlange eines echten Reparaturbetriebs verwendet, nicht als Proof of Concept.

Inhalt

• Was du damit tatsächlich tun kannst

• Tool-Referenz

• Was das nicht ist

• Schnellstart

• Manuelle Einrichtung

• Alle Konfigurationsoptionen

• Fehlerbehebung

• FAQ

• Sicherheit

Related MCP server: TicketAI

Was du damit tatsächlich tun kannst

Sobald es in deinen KI-Assistenten eingebunden ist, kannst du einfach mit deinen RepairDesk-Daten sprechen, anstatt durch die Web-UI zu klicken. Einige reale Beispiele:

Empfang / Triage

• „Ticket T-15423 nachschlagen" – vollständige Ticketdetails: Kunde, Gerät, Status pro Gerät, Notizen.

• „Wie ist der Status von Sarah Millers Telefon?" – sucht Tickets nach Kundenname/Schlüsselwort.

• „Zeig mir alles, was 'Ausstehend' oder 'Warten auf Teile' ist" – filtert Tickets nach Status.

• „Was ist Dave gerade zugewiesen?" – filtert Tickets nach Techniker.

• „Ruf Johns Kontaktdaten ab" – Kundensuche nach Name, Telefon oder E-Mail.

Workflow / Werkstattarbeit

• „Füge T-15423 eine Diagnosenotiz hinzu: Bildschirm ersetzt, Akku getestet OK"

• „Weise Ticket T-15490 Dave zu"

• „Markiere T-15423 als repariert" – der Server fragt zuerst nach Bestätigung und weist darauf hin, dass dieser Status automatisch eine Kunden-SMS/E-Mail in RepairDesk auslöst.

• „Erstelle ein Ticket für diesen Kunden: iPhone 13, Bildschirmtausch" – auch hier ist vor dem tatsächlichen Erstellen eine Bestätigung erforderlich.

Geld / Verwaltung

• „Welche Rechnungen sind aus dem letzten Monat noch unbezahlt?"

• „Wie hoch ist der offene Betrag auf Rechnung 8821?"

• „Haben wir einen iPhone-13-Akku auf Lager?" – Inventarsuche.

• „Liste alle unsere Techniker auf" / „Welche Zahlungsmethoden haben wir eingerichtet?"

• „Welche Reparaturkategorien/Gerätetypen haben wir konfiguriert?" – nützlicher Kontext beim Erstellen eines Tickets oder beim Diagnostizieren, was ein Gerätemodell in deinem System überhaupt ist.

Da dies über einen echten KI-Assistenten läuft und nicht über ein festes Dashboard, kannst du diese natürlich verketten – „finde alle überfälligen Rechnungen für Kunden mit noch offenem Ticket" – und der Assistent löst es über Tools hinweg, anstatt dass du zwei Bildschirme manuell abgleichst.

Tool-Referenz

Sicherheitsvorkehrung: repairdesk_tickets_write erfordert confirmed: true, bevor eine Statusänderung angewendet wird, und warnt, wenn der Zielstatus einer ist, bei dem RepairDesk den Kunden automatisch benachrichtigt (Repariert, Abholbereit, Abgeschlossen, Warten auf Kunde, Warten auf Angebot, Storniert). Du musst nichts tun, damit das funktioniert – antworte einfach mit „Ja", wenn dein Assistent die Bestätigungsabfrage weiterleitet.

Praktisches Detail: Ticketabfragen/-schreibvorgänge akzeptieren entweder das Bestell-ID-Format von RepairDesk (T-15423) oder die interne numerische Ticket-ID – du musst nie wissen, welche du hast, der Server löst es für dich auf.

Was das nicht ist

Dies deckt die Leseseite von RepairDesk sowie die Kern-Ticket-Workflow-Schreibvorgänge ab. Es deckt nicht Kostenvoranschläge, Terminerstellung, POS/Verkaufstransaktionen, Inventar-Schreibvorgänge, Zahlungserfassung, Ticket-Bild-/Anhang-Upload oder Webhooks ab. PRs sind willkommen, wenn du eines davon brauchst.

Schnellstart

Du musst kein Entwickler sein, um das auszuführen – nur vertraut damit, ein paar Befehle in ein Terminal zu tippen. Gesamtzeit: etwa 5 Minuten.

1. Node.js installieren (falls du es nicht hast)

Lade es von nodejs.org herunter und installiere es – nimm die „LTS"-Version. Dadurch werden sowohl node als auch npm installiert. Um zu prüfen, ob es funktioniert hat, öffne ein Terminal und führe aus:

node --version

Du solltest so etwas wie v20.x.x sehen (alles ab 18 ist in Ordnung).

2. Code holen

Wenn du Git hast:

git clone https://github.com/codeyoc/repairdesk-mcp.git
cd repairdesk-mcp

Wenn nicht: Klicke auf den grünen Code-Button auf der GitHub-Repo-Seite → Download ZIP → entpacke es irgendwohin → öffne ein Terminal in diesem Ordner.

3. Deinen RepairDesk-API-Schlüssel holen

In deinem RepairDesk-Admin: Einstellungen → API. Kopiere den dort angezeigten Schlüssel – das Setup-Skript fragt im nächsten Schritt danach. Behandle ihn wie ein Passwort: Er gewährt vollen Lese-/Schreibzugriff auf die Daten deines Shops (siehe Sicherheit).

4. Setup-Skript ausführen

node setup.mjs

Das ist der schnellste Weg und erledigt alles: Es führt bei Bedarf npm install für dich aus, fragt nach deinem API-Schlüssel, fragt, welchen KI-Assistenten du verwendest (Claude Code, Claude Desktop, Codex CLI oder OpenCode), und schreibt die Konfiguration automatisch für dich – wobei es zuerst eine Sicherung einer vorhandenen Konfigurationsdatei erstellt. Wenn du etwas anderes verwendest, gibt es den Konfigurationsblock aus, den du selbst einfügen kannst.

Wenn du es lieber von Hand machst – oder dein Client nicht einer der vier oben genannten ist – siehe stattdessen Manuelle Einrichtung unten. In jedem Fall führe zuerst selbst npm install aus, wenn du das Skript überspringst.

5. Ausprobieren

Frag deinen Assistenten etwas wie „Verwende RepairDesk, liste meine 5 neuesten Tickets auf". Wenn er mit echten Ticketdaten zurückkommt, bist du fertig.

Manuelle Einrichtung

Überspringe das, wenn node setup.mjs bei dir bereits funktioniert hat. Andernfalls führe zuerst npm install in diesem Ordner aus und verbinde dann deinen Client von Hand:

Führe das von überall aus aus, ersetze den Pfad durch den vollständigen Pfad zu dem Ordner, in den du entpackt/geklont hast, und den Schlüssel durch deinen echten:

claude mcp add repairdesk \
  --env REPAIRDESK_API_KEY=your_key_here \
  --env REPAIRDESK_USER_AGENT=YourShopName-MCP/1.0 \
  -- node /full/path/to/repairdesk-mcp/server.mjs

Öffne (oder erstelle) die Konfigurationsdatei für dein Betriebssystem:

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

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

• Linux: ~/.config/Claude/claude_desktop_config.json

Füge das hinzu (führe es mit allem zusammen, was bereits in mcpServers steht, falls die Datei nicht leer ist):

{
  "mcpServers": {
    "repairdesk": {
      "command": "node",
      "args": ["/full/path/to/repairdesk-mcp/server.mjs"],
      "env": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

Speichere die Datei und beende und öffne Claude Desktop vollständig neu (nicht nur das Fenster schließen).

Bearbeite (oder erstelle) ~/.codex/config.toml und füge hinzu:

[mcp_servers.repairdesk]
command = "node"
args = ["/full/path/to/repairdesk-mcp/server.mjs"]

[mcp_servers.repairdesk.env]
REPAIRDESK_API_KEY = "your_key_here"
REPAIRDESK_USER_AGENT = "YourShopName-MCP/1.0"

Starte eine neue Codex-Sitzung und führe /mcp aus, um zu bestätigen, dass die Verbindung hergestellt wurde. (Codex hat auch einen interaktiven Befehl codex mcp add, falls du das dem Bearbeiten der Datei vorziehst – prüfe codex mcp add --help für die genauen Flags deiner installierten Version.)

Öffne (oder erstelle) die Konfigurationsdatei für dein Betriebssystem:

• Mac/Linux: ~/.config/opencode/opencode.json

• Windows: %APPDATA%\opencode\opencode.json

Füge das hinzu (führe es mit allem zusammen, was bereits in mcp steht, falls die Datei nicht leer ist):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "repairdesk": {
      "type": "local",
      "command": ["node", "/full/path/to/repairdesk-mcp/server.mjs"],
      "enabled": true,
      "environment": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

Starte OpenCode neu, um es zu übernehmen.

Die oben verwendete command/args/env-Form (Claude Code/Desktop) ist der De-facto-Standard – die meisten MCP-Clients folgen ihm, nur in einer anderen Einstellungsdatei. Prüfe in der Dokumentation deines Clients, wo diese Datei liegt; der Block selbst sollte unverändert funktionieren.

Verwende den vollständigen, absoluten Pfad zu server.mjs (z. B. /Users/you/repairdesk-mcp/server.mjs oder C:\Users\you\repairdesk-mcp\server.mjs) – ein relativer Pfad schlägt fehl, weil dein KI-Client nicht aus diesem Ordner heraus ausgeführt wird.

Alle Konfigurationsoptionen

Alles unten gehört in den env/environment-Block, den die Konfiguration deines Clients verwendet (setup.mjs erledigt das für dich) – nicht in eine .env-Datei, da die meisten MCP-Clients eine solche nicht automatisch lesen. .env.example in diesem Repo listet dieselben Variablen als Referenz auf.

Alternative: Konfigurationsdatei statt Umgebungsvariablen. Wenn Ihre Einrichtung Umgebungsvariablen unpraktisch macht, erstellen Sie eine config.json (gitignored) neben server.mjs:

{
  "repairdesk_api_key": "your_key_here",
  "repairdesk_base_url": "https://api.repairdesk.co/api/web/v1"
}

Sie wird bei jedem API-Aufruf neu gelesen, sodass Sie den Schlüssel rotieren können, ohne den Server neu zu starten. Wenn beides vorhanden ist, haben Umgebungsvariablen Vorrang vor dieser Datei.

Ratenbegrenzung – die 100/Minute-Sache

RepairDesks dokumentierte Obergrenze ist 100 Anfragen pro Minute pro API-Schlüssel (manche Pläne erlauben bis zu 120 – prüfen Sie Ihren eigenen Plan, wenn Sie unsicher sind). Dieser Server übernimmt das automatisch für Sie:

• Jeder ausgehende Aufruf wird durch eine einzige Drosselung in eine Warteschlange gestellt, die mindestens REPAIRDESK_MIN_INTERVAL_MS (Standard 600 ms ≈ 100/min) zwischen Anfragen wartet – so löst das Anfordern einer großen Menge von Tickets selbst keinen Ratenbegrenzungsfehler aus.

• Wenn RepairDesk weiterhin einen 429 (Ratenbegrenzung) zurückgibt – z. B. weil ein anderes Tool denselben Schlüssel ebenfalls stark beansprucht – wartet der Server automatisch und versucht es einmal erneut, bevor er aufgibt.

• Sie müssen nichts konfigurieren, damit das funktioniert. Ändern Sie REPAIRDESK_MIN_INTERVAL_MS nur, wenn Sie ständig Ratenbegrenzungsfehler sehen (erhöhen Sie ihn) oder wenn Sie wissen, dass Ihr Plan eine höhere Obergrenze erlaubt und Sie schnellere Massenabfragen wünschen (senken Sie ihn vorsichtig).

Fehlerbehebung

„RepairDesk API returned 401 Unauthorized" / „Unauthorized" in der Antwort Ihr API-Schlüssel ist falsch, wurde widerrufen oder wurde nicht übernommen. Überprüfen Sie den Schlüssel in Einstellungen → API in RepairDesk und dass er in der Konfiguration Ihres MCP-Clients korrekt geschrieben ist (kein versehentliches Leerzeichen, nicht noch YOUR_REPAIRDESK_API_KEY_HERE). Starten Sie Ihren KI-Client nach jeder Konfigurationsänderung vollständig neu – die meisten laden die MCP-Konfiguration nicht live neu.

Anfragen schlagen sofort fehl / wirken wie blockiert, nicht authentifiziert RepairDesks Cloudflare blockiert Anfragen mit einem leeren oder standardmäßig aussehenden User-Agent. Setzen Sie REPAIRDESK_USER_AGENT nicht auf eine leere Zeichenfolge.

„RepairDesk API rate limit hit twice in a row (429)" Sie machen Anfragen schneller als das Limit Ihres Schlüssels, selbst nach dem eingebauten erneuten Versuch. Erhöhen Sie REPAIRDESK_MIN_INTERVAL_MS (versuchen Sie 1000) in Ihrer Konfiguration.

„Ticket T-XXXXX not found – could not resolve to internal ID" Überprüfen Sie, ob die Bestell-ID korrekt ist und in diesem RepairDesk-Shop existiert. Wenn Sie stattdessen die interne numerische ID haben, funktioniert das auch – übergeben Sie sie direkt.

„RepairDesk API request timed out after 15000ms" Normalerweise ein Netzwerk-/Firewall-Problem beim Erreichen von api.repairdesk.co, oder REPAIRDESK_BASE_URL ist falsch. Überprüfen Sie, ob Sie diesen Host von dem Ort aus erreichen können, an dem dieser Server läuft.

Ihr KI-Assistent sieht das Tool überhaupt nicht

• Stellen Sie sicher, dass der Pfad in args absolut ist, nicht relativ, und tatsächlich auf server.mjs zeigt.

• Stellen Sie sicher, dass Sie npm install in diesem Ordner ausgeführt haben (fehlendes node_modules = der Server kann nicht starten).

• Beenden und starten Sie Ihren KI-Client vollständig neu – schließen Sie nicht nur das Chat-Fenster.

• Führen Sie node /full/path/to/server.mjs direkt in einem Terminal aus – wenn ein Fehler auftritt, sehen Sie das eigentliche Problem statt einer allgemeinen „Tool nicht verfügbar"-Meldung Ihres Clients.

node setup.mjs meldet, dass claude/codex nicht in Ihrem PATH gefunden wurden Das ist in Ordnung – es fällt darauf zurück, den Konfigurationsblock auszugeben, den Sie von Hand einfügen können (siehe Manuelle Einrichtung). Das bedeutet nur, dass diese CLI nicht installiert ist oder nicht in Ihrem PATH ist; es bedeutet nicht, dass der MCP-Server selbst defekt ist.

Immer noch festgefahren? Eröffnen Sie ein Issue in diesem Repository mit der Fehlermeldung (schwärzen Sie zuerst Ihren API-Schlüssel, falls er irgendwo in der Ausgabe erscheint).

Häufig gestellte Fragen

Ist das ein offizielles RepairDesk-Tool? Nein. Es ist unabhängig erstellt und gepflegt und nutzt die öffentliche API von RepairDesk. Verwenden Sie es nach eigenem Ermessen.

Kostet der Betrieb etwas? Nein – es werden lediglich dieselben API-Aufrufe getätigt, die Ihr RepairDesk-Plan bereits erlaubt. Es fallen keine zusätzlichen Gebühren von diesem Projekt an. (Ihr KI-Assistent-Abo, z. B. Claude, ist getrennt und steht in keinem Zusammenhang mit diesem Server.)

Kann ich das auch mit etwas anderem als Claude verwenden? Ja – MCP ist ein offener Standard. setup.mjs konfiguriert Claude Code, Claude Desktop, Codex CLI und OpenCode direkt; alles andere, das MCP über stdio spricht (Cursor, Windsurf usw.), kann diesen Server ebenfalls verwenden, über die manuelle Konfiguration in Manuelle Einrichtung.

Kann ich das für mehrere RepairDesk-Shops ausführen? Ja – registrieren Sie es mehrmals unter verschiedenen Namen (z. B. repairdesk-store1, repairdesk-store2) in Ihrem MCP-Client, jeweils mit eigenem REPAIRDESK_API_KEY.

Wird mein KI-Assistent versehentlich meine Kunden per E-Mail oder SMS kontaktieren? Nur repairdesk_tickets_write kann das auslösen, und nur über eine Statusänderung – die immer ein explizites confirmed: true erfordert und in der Tool-Beschreibung gekennzeichnet ist, wenn der Zielstatus einer der benachrichtigenden Status von RepairDesk ist. Es wird nicht stillschweigend passieren.

Sicherheit

Ihr REPAIRDESK_API_KEY gewährt vollen Lese-/Schreibzugriff auf die Kunden- und Finanzdaten Ihres Shops. Bewahren Sie ihn in der Umgebungskonfiguration Ihres MCP-Clients auf, niemals in einer committeten Datei. config.json und .env sind hier genau aus diesem Grund gitignored – verwenden Sie sie lokal, wenn Sie eine Datei gegenüber Umgebungsvariablen bevorzugen, aber committen Sie keine ausgefüllte Kopie. Sicherheitsproblem gefunden? Bitte eröffnen Sie ein Issue (oder einen privaten Bericht, falls Ihr Host das unterstützt) anstelle eines öffentlichen PRs mit Exploit-Details.

Lizenz

MIT – siehe LICENSE. Bereitgestellt wie besehen, ohne Gewähr – Sie sind verantwortlich für die Verwendung gegenüber Ihrem eigenen RepairDesk-Konto.