Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.
Der Server schreibt auf stderr und in die Datei ~/.claude/mcp-servers/osticket/logs/server.log. Mit LOG_LEVEL=debug in der .env gibst du mehr Meldungen aus.
tail -f ~/.claude/mcp-servers/osticket/logs/server.log
Die Datei enthält Start- und Stoppmeldungen, Warnungen zur Zustandsprüfung und zu Wiederholungen. Die Ursache vieler Tool-Fehler steht dort nicht, siehe den Abschnitt zu Unexpected error.
| Symptom | Ursache und Lösung |
|---|---|
Der Client zeigt keine osticket_*-Tools |
Server nicht registriert, dist/index.js fehlt oder der Client wurde nicht neu gestartet. Baue mit npm run build und prüfe die Registrierung |
Missing required environment variable |
OSTICKET_API_URL oder OSTICKET_API_KEY ist nicht gesetzt. Prüfe ~/.claude/mcp-servers/osticket/.env |
OSTICKET_API_URL must use HTTPS |
Die URL beginnt mit http://. Nutze https:// oder setze für lokale Tests ALLOW_HTTP=true |
Invalid OSTICKET_API_URL |
Die URL ist keine gültige URL, etwa weil das Schema fehlt |
Invalid OSTICKET_DEFAULT_TOPIC_ID oder Invalid OSTICKET_DEFAULT_EMAIL |
Der Wert hat das falsche Format |
Die .env wird nicht gefunden |
Sie wird nur unter ~/.claude/mcp-servers/osticket/.env und im Arbeitsverzeichnis gesucht. Übergib die Variablen sonst über env im Client |
Warnung Health check failed im Log |
Die Anfrage an /api/tickets-stats.php ist gescheitert. Prüfe URL, Key, Plugin API Endpoints und die Berechtigung can_read_stats oder can_read_tickets |
| Meldung | Bedeutung und Lösung |
|---|---|
Authentication failed. Check OSTICKET_API_KEY ... (401) |
Der Key fehlt, ist unbekannt oder inaktiv, oder die IP passt nicht. Das Plugin API Endpoints antwortet auch dann mit 401, wenn dem Key nur die Berechtigung für diesen Endpunkt fehlt. Den genauen Text blendet der Server aus. Prüfe deshalb Key, IP und Berechtigung in osTicket |
Permission denied ... (403) |
Bei Subtickets fehlt can_manage_subtickets oder die Abteilungsbeschränkung des Keys schließt das Ticket aus. Beim Anhang-Download gibt es keinen Anhang-Eintrag zu dieser file_id |
Resource not found ... (404) |
Ticket oder Datei existiert nicht. Beim Erstellen kann das auch heißen, dass der Endpunkt /api/wildcard/tickets.json fehlt, weil das Plugin API Key Wildcard nicht aktiv ist |
Feature not available ... (501) |
Das Plugin Subticket Manager ist nicht installiert oder nicht aktiv |
osTicket API error: ... (422) |
Die Verknüpfung besteht schon oder das Kind hat bereits ein anderes Elternticket. Der Text von osTicket steht in der Meldung |
osTicket API error: ... (400) |
Das Plugin lehnt die Eingabe ab, zum Beispiel einen ungültigen Wert oder ein Elternticket, das selbst ein Kind ist. Der Text von osTicket steht in der Meldung |
Request timed out |
osTicket antwortet nicht binnen 10 Sekunden, auch nach den Wiederholungen |
Cannot connect to osTicket server |
Der Host verweigert die Verbindung oder bricht sie ab |
osTicket host not reachable |
Der Hostname der URL lässt sich nicht auflösen |
TLS/SSL connection error |
Zertifikat oder Protokoll sind fehlerhaft. Behebe das Zertifikat. OSTICKET_API_REJECT_UNAUTHORIZED=false umgeht die Prüfung, ist aber unsicher |
Unexpected error occurred. Check server logs for details. Diese Meldung ersetzt die genaue Ursache und der Server schreibt sie nicht ins Log. Typische Gründe sind:
osticket_get_ticket ohne id und number.Prüfe in diesen Fällen die Eingaben.
Die Liste ignoriert meinen Abteilungsfilter. Der Parameter departmentId von osticket_list_tickets hat derzeit keine Wirkung: Der Server sendet ihn als departmentId, das Plugin liest nur department. Die Liste kommt ungefiltert zurück. Filtere die Ergebnisse selbst, etwa nach dem Feld für die Abteilung in der Antwort.
Die Liste ignoriert meinen Statusfilter. Das Plugin filtert nicht, wenn der Statusname keinem Status der Instanz entspricht. Nutze die Statusnamen deiner Instanz, in der Regel open, closed, resolved und archived.
osticket_update_ticket meldet Erfolg, ändert aber nichts. Ein Aufruf mit nur number besteht die Prüfung und sendet nichts Sinnvolles. Gib mindestens ein Feld an.
osticket_get_ticket mit id liefert das falsche Ticket. Der Server sendet die id als Ticketnummer, und das Plugin sucht zuerst nach der Nummer. Nutze nach Möglichkeit number.
Ein Ticket wurde doppelt erstellt. Läuft die Antwort in ein Timeout, wiederholt der Server die Anfrage. Prüfe vor dem erneuten Erstellen mit osticket_search_tickets, ob das Ticket schon existiert.
Ein großer Anhang lässt sich nicht herunterladen. Die Antwort von osTicket darf mit Base64 höchstens 10 MB groß sein, also Dateien bis etwa 7,5 MB.
Die Suche findet eine Ticketnummer nicht. Das Plugin durchsucht den Betreff. Hol ein Ticket anhand der Nummer mit osticket_get_ticket.
total bei Liste und Suche ist zu klein. Das Tool liefert keine Gesamtzahl. total bei der Suche ist die Zahl der zurückgegebenen Treffer. Frag mit offset weitere Seiten ab, solange has_more wahr ist (nur osticket_list_tickets).
osTicket liegt in einem Unterverzeichnis. Der Server verwirft den Pfad der Basis-URL und ruft https://host/api/... auf. osTicket muss unter der Wurzel des Hosts erreichbar sein.