mcp-connectwise-psa

Ein MCP-(Model Context Protocol)-Server für ConnectWise PSA (Manage) — kuratierte Tools über 8 Toolsets für Techniker, Disponenten und Abrechnung, plus eine Notluke für den Rest der API und ein schreibgeschütztes SQL-Toolset für On-Premises-Betriebe, sodass ein KI-Assistent PSA so verwendet, wie es die jeweilige Rolle tut:

• Tickets — Suche / eigene Tickets / Details mit Notizen, Anlegen, Status/Priorität/Verantwortlicher aktualisieren, Diskussions-/interne Notizen hinzufügen, Board-/Status-/Prioritätsfindung und Zeiterfassungs-/ und Aufgaben pro Ticket- Zeit — Zeiten gegen Tickets buchen, eigene Zeiten prüfen, Arbeitsrollen nachschlagen, und Zeitbrachzettel auflisten und einreichen

• Firmen & Kontakte — schnelle Suche, Kontaktdetails (Telefon/E-Mail), Firmenstandorte

• Konfigurationen — background. Geräte/Assets mit Seriennummern, IP-Adressen, OS, Garantie (schreibgeschützt)

• Einsatzplanung (Zeitplan) — Einträge (liste/eigene/anlegen/umschreiben/stornieren) und Mitarbeiter mit Zeitzone, Arbeitszeiten und freier- vs. gebuchter-Verfügbarkeit

• Rechnungsstellung (Finanzen, Schreibschutz) — Rechnungen, Vereinbarungen und unverrechnete, fakturierbare Zeit in Rechnung

• SQL (nur On-Premises) — schreibgeschütztes T-SQL direkt gegen die Datenbank## Übersetzung

mcp-connectwise-psa

Ein MCP-(Model Context Protocol)-Server für ConnectWise PSA (Manage) — kuratierte Tools über 8 Toolsets für Techniker, Disponenten und Abrechnung, plus eine Notluke für den Rest der API und ein schreibgeschütztes SQL-Toolset für Vor-Ort-Betriebe, sodass ein KI-Assistent PSA so bedient, wie es die jeweilige Rolle tut:

• Tickets — Suche / eigene Tickets / vollständige Details mit Notizen, Anlegen, Status/Priorität/Verantwortlichen aktualisieren, Diskussions- und interne Notizen, plus Erkundung von Board-Status-Priorität sowie Zeiteinträgen und Aufgaben pro Ticket

• Zeit — Zeiten auf Tickets buchen, eigene Zeiten überprüfen, Arbeitsrollen nachschlagen und Vorschläge auflisten und einreichen

• Firmen & Kontakte — schnelle Suche, Kontaktdetails (Telefon/E-Mail), firmeneigene Standorte

• Konfigurationen — Geräte/Assets mit Seriennummern, IP-Adressen, OS, Garantie (schreibgeschützt)

• Einsatzplanung (Zeitplan) — Einträge (list/mine/anlegen/verschieben/stornieren) und Mitarbeiter mit Zeitzone, Arbeitszeiten und Verfügbarkeit frei-verbucht

• Rechnungsstellung (Finanzen, schreibgeschützt) — Rechnungen, Vereinbarungen und unk..., deine / in Rechnung zu gebende Zeit

• SQL (nur Vor-Ort) — schreibgeschütztes T-SQL direkt gegen die cwwebapp_*-Datenbank für Berichte über Tabellengrenzen, die REST nicht abbilden kann, mit einem durchsuchbaren Schema-Katalog und Ablage gespeicherter Queries, die der Assistent erweitern kann. Aktiviert durch die Option CW_DB_*; wo diese gesetzt ist, hat sie auch jede Sitzung, die seine Toolsets nicht einschränkt.

• Toolsets & Personas — aktivieren Sie nur das, was eine Sitzung braucht, über den x-cw-toolsets-Header (oder CW_TOOLSETS); Voreinstellungen tech / dispatch / “invoicing / all. Standard ist ist all – einschränken pro Sitzung, wenn kleinere Toolfläche gewünscht wird. Jedes Tool meldet außerdem sein Toolset als _meta.group, so ein Aggregator (das MSPStack-Gateway) Tools nach Fähigkeiten gruppieren und umschalten kann.

• API-Schlüssel pro Mitglied (BYOK) — jeder Benutzer liefert seine eigene ConnectWise-Memberschlüssel; ConnectWise erzwingt die Sicherheitsrolle dieses Mitglieds, und jedes Schreiben wird der tatsächlichen Person zugeordnet.

• Transporte — stdio für lokalen Einsatz, streamable HTTP für freigegebene Bereitstellung; Docker-Image enthalten

Schnellstart (lokal, stdio)

(BEREICH GXP1)

Konfiguration von Claude Desktop / Claude Code:

(BEREICH GXP2)

Eine clientId ist für die ConnectWise-API erforderlich — registrieren Sie eine (kostenlose) Integration unter developer.connectwise.com. API-Maschlüssel werden in ConnectWise erstellt unter My Account → API Keys (pro Anzahl) oder System → Members → API Members (Integrationskonten).

HTTP-Bereitstellung

(BEREICH GXP3)

Oder mit Docker: `docker build -t mcp-connectwise-psa . && docker run -p 3000:3000 -e CW_SITE -e CW_COMPANY_ID -e CW_CLIENT_ID mcp-connectwise-psa -Bereitstellung

Sitzungen werden im Speicher gehalten — führen Sie die Instanz einzeln aus (oder Sticky-Sitzungen/Sessions).

Bestellsteuerung — eigene Schlüssel einbringend (BYOK)

Über HTTP gibt es kein Rollensystem auf MCP-Ebene Hier findet die MCP-Roll. Jede Sitzung präsentiert ihre eigenen ConnectWise-API-Schlüssel des Mitglieds, und ConnectWise selbst ist die Zugriffskontrolle: Die Sicherheitsrolle des Mitglieds entscheidet, was Erfolg hat, und jede Notiz und jeder Zeiteintrag wird diesem Mitglied zuordnet.

Sendet die Keys auf der Initialize-Anfrage (und bei jeder weiteren Anfrage in der Sitzung):

(BEREICH GXP4)

• Funktion ohne Sicht-/Anforderung ohne Schlüssel wird mit 401 abgelehnt; beide Schlüssel-Header müssen zusammen angegeben werden.

• Die Schlüssel werden nie protokolliert. Eine Sitzung ist an einen SHA-256-Hash des Schlüsselpaars gebunden; ein anderes Paar bei gleicher Sitzungs-ID ergibt 403.

• API-Schlüssel werden in ConnectWise unter My Account → API Keys . Jeder Techniker verwendet seinen eigenen.

Lokale stdio in Einzelbetrieb verwendet hingegen die CW_PUBLIC_KEY/CW_PRIVATE_KEY aus der Umgebung statt der Header.

Related MCP server: superops-mcp

Toolsets

Die Tools werden in Toolsets gruppiert, so eine Sitzung nur die benötigte Kapazität sieht — ein Disponent braucht nicht die Rechnungslegung, und eine kleine Werkzeug-Fläche hält den Assistentenfokus (und den Kontext günstig). Ob ein Schreibvorgang tatsächlich gelingt, entscheidet weiterhin die ConnectWise-Sicherheitsrolle des Mitglieds.

Presets bündeln Themen pro Persona: tech = tickets + time + companies + configurations · dispatch = tickets + schedule + companies + configurations · invoicing = finance + time + companies · all = aller Schlüssel. Die Persona-Presets schließen sql bewusst aus — eine Letechnik-Läufer-Fläche und Eineite-Hupfläche.

Das advanced-Toolset ist die Notluke (in all, aber in keinem Persona-Preset): cw_find_endpoint sucht einen gebündelten Katalog der vollständigen ConnectWise-API, und hw_get führt ein read-only GET auf jedem Pfad aus — sodass ein Assistent den langen Nachlauf erreicht (Beschaffung, Schaltung, Projekte, System…), was die kuratierten Tools nicht abdecken. Zum Weglassen Trigger Sie die Schlüssel oder ein Persona-Preset (x-cw-toolsets: tech).

Toolsets werden mit einer Kommaliste aus Schlüsseln und Presets eingestellt:

• HTTP — der x-cw-toolsets-Header pro Sitzung: x-cw-toolsets: dispatch oder x-cw-toolsets: tech,finance.

• stdio — die Umgebungsvariable CW_TOOLSETS oder --toolsets-Flag: CW_TOOLSETS=invoicing.

Der Standard ist das all-Preset — jede Fähigkeit für die der Server konfiguriert ist; ein Client, der eine kleinere Fläche will, nennt die gewünschten Schlüssel oder Persona. Unbekannte Schlüssel in CW_TOOLSETS/--toolsets schlagen sofort fehl; unbekannte Tokens im x-cw-toolsets-Header werden ignoriert. Einzige Zerstörungsfunktion ist cw_zz unbearbeitete_Schedule-Eintrag(dispatch); finance ist schreibgeschützt.cw_db_save_query` schreibt, aber in die Query-Datei — Datenbankzugriff ist selbst per Grant nur SELECT.

Ausnahme: das sql-Toolset

Jedes andere Toolset läuft auf eigenen ConnectWise-Schlüsseln des Aufrufers; ConnectWise filtert daher, was zurückkomt. sql nicht: es liest aus der Datenbank über den Konsistent clean “ser_weiten Leser; die Ergebnisse sind keinem Mitglied zugeordnet und nicht an dessen Sicherheitsrolle, Board-Beschränkungen oder Datensatz-Rechte gefiltert.

Die Konfiguration von CW_DB_* ist daher die entscheidende Entscheidung. Einmal Datenbank auf dem Server, ist sql ein gewöhnlicher Schlüssel: er ist Minimal in all, in der Standardaus wahl, und jede Sitzung, die keine einschränkten Toolsets hat, kann die gesamte PSA-Datenbank.

Ein Server ohne CW_DB_* and dies entschieden aus, damit keine Fehlschläge für Bereitstellungen entstehen, die es nie wollten. Falls Datenbankzugriff nur für bestimmte Aufrufer nötig ist, einrichten separat pro Sitzung (x-cw-toolsets: tech) bzw. vor dem Server – ein aggregierender Gateway früchtigene cw_db_*-Tools getrennt. Die Begrenzung des Schadens auf der Serverseite ist der Login: siehe Runbook unten; den Login auf db_datareader begrenztet sowie Spalten mit Anmeldedaten verweigert.

SQL-Toolset (On-Prem-Datenbank)

In Cloud-gehostetem ConnectWise gibt es keinen Datenbankzugriff, Das Toolset ist nur für On-Prem-Bereitstellungen. Sicher an der Manage-Datenbank mit einem genau dafür erstellten Login:

CW_DB_HOST=sqlhost CW_DB_NAME=cwwebapp_acme \
CW_DB_USER=cw_mcp_ro CW_DB_PASSWORD=… \
CW_DB_QUERY_LIBRARY=/data/cw-queries.json \
node dist/index.js

Das ist alles: Con Datenbankinvariation ist SQL. Dazu gehört sql in der Standardauswahl. Wird sql ohne CW_DB_* benannt, schlägt die Startung fehl (eine Auswahl, die es also enthält, wie all, wird entfernt). Erst beiare in der Sitzung genutzten Tool verbindet den Server mit der Datenbank.

Beginnen Sie bei den Reporting-Views: ConnectWise liefert denormalisierte v_rpt_*-Views, die bereits Board, Status, Firma, Kontakt — v_rpt_service, v_rpt_time, v_rpt_company, v_rpt_invoices, v_rpt_agreementlist — auf einen Datensatz verbinden. cw_db_find_table kennt diese und die Basistabellen dahinter; es führt nur Schlüsselspalten, denn die exakte Spaltenliste ist eine einzige INFORMATION_SCHEMA-Abfrage entfernt und für Ihre Version immer korrekt.

**Die Query-Ablage ist der im Git committete Kern plus ein schreibbares Overlay unter CW_DB_QUERY_LIBRARY (JSON, { version, queries[] }). Overlay-Einträge gewinnen nach Slug, cw_db_save_query fzelfde an, scripts/import-queries.mjs füllt sie von einer vorhanden BrightGauge Export:

node scripts/import-queries.mjs /path/to/brightgauge-export

Importierte Query bleiben daher außerhalb dieses Repositories – sie sind Ihre Berichte und können Firmennamen und Sätze hochhalten. In einem Container muss CW_BQ_QUERY_LIBRARY auf gespeicherten Speicher zeigen oder gespeicherte Abfragen sterben mit dem Container.**.

Der Login ist die Sicherheitsgrenze

Es gibt keine Statement-Validierung: Das Server sendet das Modell-SQL so an den SQL Server, wie geschrieben; was der Login tun darf, ist exakt das, was passieren kann. Zwei Scripts richten es ein und belegen es.

Anlegen — die vier Variablen oben editieren, as sysadmin ausführen. @WhatIf ist Standard 1, d. h. erste Lauf druckt nur den Plan:

sqlcmd -S SQLHOST\CWPROD -d master -i scripts/create-readonly-login.sql

Es erzeugt Login in keiner Serverrolle, fügt zu db_datareader in einer Datenbank hinzu, DENYs den Rest (EXECUTE, alle Schreibungen, DDL, BACKUP) und DENYs SELECT auf jeder Anmeldedaten-ähnlichen Spalte, die sie entdeckt — die Namen unterscheiden sich zwischen Manage-Versionen, und jede MSP fügt eigene hinzu, deswegen werden sie gefunden statt hartkodiert. Wiederholungen sind sicher und die Art, die Threads nach einem Upgrade neu anzuwenden. Es berichtet die instanzweit abgeschalteten Einstellungen, die ausgeschaltet werden müssen, die aber nie geändert werden: xp_cmdshell deaktivieren kann andere Apps zerbrechen, das wird also nicht entsatz.

Prüfen — als neuer Login, nicht als Admin:

sqlcmd -S SQLHOST\CWPROD -d cwwebapp_acme -U cw_mcp_ro -P '<password>' -i scripts/verify-readonly-login.sql

Jede Prüfung gibt PASS oder FAIL aus: SELECT funktioniert, UPDATE/CREATE TABLE werden verweigert (innerhalb einer Transaktion, die immer zurückgerollt wird, falls ein DENY fehlt), xp_cmdshell/sp_OACreate/OPENROWSET(BULK …) sind nicht erreichbar, eine Credential-Spalte ist nicht lesbar, und der Login befindet sich in keiner erhöhten Rolle. Ein FAIL bedeutet: Aktivieren Sie das Toolset noch nicht.

Zwei Konsequenzen, die Sie vorab kennen sollten:

• SELECT * schlägt fehl bei jeder Tabelle mit einer verweigerten Spalte, anstatt die anderen Spalten zurückzugeben. Genau das ist der Sinn; die Fehlermeldung des Tools weist das Modell an, seine Spalten zu benennen.

• EXECUTE ist die Berechtigung, auf die es ankommt. Mit ihr wird „schreibgeschütztes SQL“ zu Remote-Codeausführung als SQL-Server-Dienstkonto — xp_cmdshell, sp_OACreate, sp_send_dbmail, xp_dirtree für NTLM-Capture. OPENROWSET/BULK INSERT lesen Dateien ganz ohne EXECUTE, weshalb Ad Hoc Distributed Queries ebenfalls deaktiviert sein müssen.

Operativ: Bevorzugen Sie ein lesbares AG-Secondary oder eine wiederhergestellte Reporting-Kopie gegenüber dem Produktions-Primary, beschränken Sie den SQL-Port per Firewall auf den MCP-Host und behalten Sie eine SQL-Audit- oder Extended-Events-Sitzung für diesen Login bei.

Konfigurationsreferenz

Hinweise & Grenzen

• Ticketsuchen suchen standardmäßig offene Tickets; Status-/Board-Namen müssen exakt übereinstimmen, Textfilter sind Teilzeichenfolgen.

• Zeitstempel müssen ganze Sekunden haben — der Server normalisiert (ConnectWise lehnt Sekundenbruchteile ab).

• Zeiteinträge erfordern für das Eintragsdatum einen offenen Zeitberichtszeitraum in ConnectWise; ist keiner vorhanden, wird die Meldung der API durchgereicht.

• /system/myAccount fehlt in einigen On-Prem-Versionen — geben Sie die Member-Kennung explizit an (CW_MEMBER_IDENTIFIER oder x-cw-member-id) für „my tickets“/„my time“.

• Diskussionsnotizen sind für Kunden sichtbar; interne Notizen nicht — das Tool macht dies explizit.

• cw_db_query stoppt bei max_rows (Standard 200) oder einem Budget von ~20.000 Zeichen und bricht die Abfrage serverseitig ab; die Antwort gibt an, welches Limit erreicht wurde. Das Zeitlimit pro Abfrage beträgt standardmäßig 30 s, höchstens 120 s.

• Die Datenbankverbindung liest mit READ UNCOMMITTED, sodass ein Reporting-Scan einen Techniker beim Speichern eines Tickets nicht blockieren kann. Der Preis sind Dirty Reads: Zählungen sind bei gleichzeitigen Schreibzugriffen nur Näherungswerte. Setzen Sie CW_DB_READ_UNCOMMITTED=false, wenn ein Bericht exakt sein muss.

• SELECT * schlägt bei jeder Tabelle mit einer DENY-Spalte fehl — benennen Sie die Spalten, die Sie benötigen.

• Cloud-gehostete ConnectWise-Instanzen haben keinen Datenbankzugriff; das sql-Toolset ist nur für On-Prem verfügbar.

Entwicklung

npm install
npm run dev          # stdio via tsx
npm run dev:http     # http via tsx
npm test             # vitest
npm run build        # tsc → dist/

Lizenz

MIT