Simpro MCP-Server

Inoffiziell. Dies ist ein unabhängiges Drittanbieter-Projekt. Es ist nicht mit Simpro verbunden, von Simpro unterstützt oder befürwortet.

Ermöglicht einem KI-Agenten, mit Ihrem Simpro-Konto zu arbeiten. Schlagen Sie fast alles aus Simpro nach, stellen Sie Zahlen zusammen, die normalerweise bedeuten würden, dass Sie durch mehrere Bildschirme klicken müssen. Sie fragen in einfachem Englisch; der Agent führt die Nachschlage- und Änderungsvorgänge in Simpro für Sie aus.

Es erreicht jeden Teil der Simpro-API, sodass der Agent auch dann darauf zugreifen kann, wenn es kein speziell dafür gebautes Tool gibt.

⚠️ Dieses Tool kann schreiben und löschen, nicht nur lesen. Es erreicht die vollständige Simpro-API, einschließlich der Endpunkte, die Datensätze aktualisieren und löschen. Ein KI-Agent, der es steuert, kann – versehentlich oder durch eine schlechte Anweisung – Angebote, Aufträge, Kunden, Katalogartikel und mehr in Ihrem Live-Simpro-Konto in großem Umfang ändern oder löschen, ohne Rückgängig-Möglichkeit. Es handelt mit den Berechtigungen, die der Schlüssel oder die Anmeldung hat, die Sie ihm geben. Geben Sie es nicht einem Agenten, dem Sie nicht vertrauen, lassen Sie es nicht unbeaufsichtigt gegen die Produktion laufen und geben Sie ihm eine Simpro-Anmeldung/einen Schlüssel, der nur auf das beschränkt ist, was es tatsächlich benötigt. Wenn Sie Nur-Lese-Sicherheit wünschen, erstellen Sie einen Simpro-Benutzer mit Nur-Lese-Berechtigungen und authentifizieren Sie sich als dieser Benutzer.

Dies wurde aus einem internen Tool entwickelt, das wir verwenden und das hinter unserem eigenen MCP-Gateway sitzt. Wir haben einige zusätzliche Funktionen hinzugefügt, um es für die Community etwas funktionaler zu machen, aber der mcbp- und OAuth-Broker-Modus werden intern von uns nicht verwendet.

Diese Software wird "wie besehen", ohne jegliche Garantie, weder ausdrücklich noch stillschweigend, bereitgestellt. Sie nutzen sie auf eigenes Risiko; die Autoren übernehmen keine Haftung für Verluste, Schäden oder Änderungen an Ihren Simpro-Daten, die durch ihre Verwendung entstehen.

Voraussetzungen

• Für die Claude-Desktop-Installation (Option 1): nur Claude Desktop und eine Simpro-OAuth-App – das .mcpb-Bundle bringt seine eigene Laufzeit mit.

• Um aus dem Quellcode auszuführen oder selbst zu hosten (Optionen 2 und 3): Node.js 24 oder neuer und npm.

• Einen Simpro-Build, den Sie erreichen können, und eine OAuth-App (oder einen Legacy-API-Schlüssel), die darin erstellt wurde – der Abschnitt zu jedem Modus sagt genau, was benötigt wird.

Related MCP server: ServiceTitan MCP Server

Inhalt

• In Claude Desktop installieren (der einfache Weg)

  • Was Sie von Simpro benötigen

  • Installieren

  • Anmelden (der OAuth-Ablauf)

  • Andere Authentifizierungsmöglichkeiten

  • Lokal aus dem Quellcode ausführen

• OAuth-Broker-Modus (für den KI-Agenten-Connector)

• HTTP-Proxy-Modus (für ein gemeinsames/gehostetes Setup)

• Welchen Modus möchte ich?

• Verbinden eines Clients (Konfigurationsausschnitte)

• Wie der Broker Simpros Anmeldung aufwertet

• Selbst bauen

1. In Claude Desktop installieren (der einfache Weg)

Keine Befehlszeile, keine Setup-Dateien. Sie installieren das .mcpb-Bundle aus den Erweiterungseinstellungen von Claude Desktop, füllen ein kurzes Formular aus und melden sich einmal in Ihrem Browser bei Simpro an. Danach bleibt der Agent angemeldet und Sie chatten einfach.

Was Sie von Simpro benötigen

Sie authentifizieren sich mit einer Simpro-OAuth-App, die Sie über den eigenen Anmeldebildschirm von Simpro anmeldet – der empfohlene Weg. Erstellen Sie eine in Simpro unter Setup → Integrationen → API → Neuer API-Schlüssel (wählen Sie eine OAuth- / "Authorization Code"-Anwendung), und notieren Sie dann:

Ein wichtiger Schritt: Setzen Sie in Ihrer Simpro-OAuth-App die Redirect-URI auf http://localhost:8237/callback. Hierhin sendet Simpro Sie nach der Anmeldung zurück. Sie muss exakt übereinstimmen. Wenn Port 8237 auf Ihrem Rechner bereits belegt ist, wählen Sie einen anderen und setzen Sie den passenden Auth-Redirect-Port auf dem Installationsbildschirm – aber die registrierte Redirect-URI muss denselben Port verwenden.

Installieren

1. Laden Sie die neueste simpro-mcp-server.mcpb-Datei von der Releases-Seite herunter.

2. Öffnen Sie in Claude Desktop Einstellungen → Erweiterungen, klicken Sie auf Erweiterte Einstellungen und dann auf Erweiterung installieren (möglicherweise müssen Sie dort zuerst Entwickler-/Erweiterungsinstallationen aktivieren). Wählen Sie die heruntergeladene simpro-mcp-server.mcpb-Datei. Ein Installationsbildschirm erscheint.

3. Füllen Sie aus:

   • Build-URL und Unternehmens-ID

   • Authentifizierungsmodus – lassen Sie authorization_code (die Browser-Anmeldung) eingestellt.

   • Client-ID und Client-Secret aus Ihrer Simpro-OAuth-App.

   • Lassen Sie Auth-Redirect-Port auf 8237, es sei denn, Sie haben einen anderen registriert.

4. Klicken Sie auf Installieren.

Anmelden (der OAuth-Ablauf)

Beim ersten Mal, wenn der Agent das Tool verwendet, öffnet sich ein Browser-Tab auf dem Simpro-Anmeldebildschirm. Melden Sie sich an und genehmigen Sie den Zugriff. Der Tab zeigt "✓ Authorisiert" – schließen Sie ihn und kehren Sie zu Ihrem Chat zurück.

Diese eine Anmeldung genügt. Das Tool speichert ein Aktualisierungstoken zwischen, sodass es über Neustarts hinweg angemeldet bleibt und Sie erst wieder aufgefordert werden, wenn dieses Token widerrufen oder abläuft. Falls das jemals passiert, öffnet es einfach wieder den Anmeldetab.

Das war's – starten Sie einen Chat und fragen Sie z. B. "zeig mir offene Angebote für Acme" oder "was ist auf Auftrag 4521?".

Seitengröße ist eine optionale Einstellung auf dem Installationsbildschirm. Lassen Sie sie bei 50. Sie begrenzt nur, wie viele Zeilen auf einmal zurückkommen, damit große Listen eine einzelne Antwort nicht überfordern – der Agent kann jederzeit nach mehr fragen.

Andere Authentifizierungsmöglichkeiten

Das Feld Authentifizierungsmodus auf dem Installationsbildschirm bietet drei Optionen:

Ihre Anmeldedaten sicher aufbewahren

Ihr Client-Secret, Aktualisierungstoken und alle API-Schlüssel werden von Claude Desktop gespeichert und nur verwendet, um mit Ihrem eigenen Simpro-Build zu sprechen. Jeder, der sie hat, kann in Simpro mit demselben Zugriff handeln, den Sie gewährt haben. Teilen Sie daher die .mcpb-Installation oder diese Werte nicht mit Personen, die diesen Zugriff nicht haben sollten. Wenn ein Anmeldedatum jemals offengelegt wird, widerrufen Sie die OAuth-App oder den Schlüssel in Simpro und erstellen Sie einen neuen.

Lokal aus dem Quellcode ausführen

Für Entwickler oder alle, die aus einem Git-Checkout statt aus dem .mcpb-Bundle ausführen. Wenn Sie die Erweiterung oben installiert haben, können Sie diesen Abschnitt überspringen.

1. Kopieren Sie .env.example → .env und setzen Sie SIMPRO_BASE_URL und SIMPRO_COMPANY_ID, plus entweder SIMPRO_CLIENT_ID + SIMPRO_CLIENT_SECRET (für die Browser-Anmeldung oder die Maschinenanmeldung) oder SIMPRO_API_KEY (den Legacy-Schlüssel).

2. Der Authentifizierungsmodus wird aus dem abgeleitet, was Sie gesetzt haben – client_credentials, wenn sowohl Client-ID als auch Secret vorhanden sind, sonst api_key. Um die Browser-Anmeldung zu erzwingen, setzen Sie SIMPRO_AUTH_MODE=authorization_code.

3. npm install && npm run build && npm start – dies läuft über stdio, genau wie die installierte Erweiterung.

Für die Browser-Anmeldung (authorization_code) können Sie sich einmal im Voraus mit npm run login anmelden – es öffnet den Simpro-Anmeldetab und speichert das Aktualisierungstoken in .simpro-tokens.json. Wenn Sie es überspringen, führt der Server dieselbe Anmeldung beim ersten Verwenden eines Tools aus. Siehe Selbst bauen für die vollständige Liste der Skripte.

2. OAuth-Broker-Modus (für den KI-Agenten-Connector)

Zum Verbinden von Simpro mit einem KI-Agenten als richtigen Connector, bei dem sich jede Person selbst über den normalen Simpro-Anmeldebildschirm bei Simpro anmeldet – kein gemeinsamer Schlüssel, keine Setup-Datei pro Person. Für die meisten, die dies auf einem Server ausführen, ist dies der Modus, den Sie möchten.

Dies ist der Modus, auf den das mitgelieferte Docker-Setup standardmäßig eingestellt ist. Es ist die sicherere Standardeinstellung: Der Server authentifiziert Benutzer selbst, anstatt einem Anmeldedatum zu vertrauen, das ihm von vorgelagerten Systemen übergeben wird. Er gehört dennoch hinter einen Reverse-Proxy, der TLS beendet und PUBLIC_URL an ihn weiterleitet – aber der Container entscheidet nie selbst, einem eingehenden Header zu vertrauen.

Simpros eigene Anmeldung ist ein OAuth-2.0-Design, mit dem sich moderne Agent-Connectors nicht direkt verbinden können. Dieser Server sitzt in der Mitte und bringt es auf den OAuth-2.1-Standard, den sie verlangen – er fügt die Sicherheitsschritte hinzu, die Simpro fehlen, während er dennoch an die echte Simpro-Anmeldung übergibt. Aus Sicht des Benutzers ist es einfach "Klicken Sie auf Verbinden, melden Sie sich bei Simpro an." Die genauen Schritte, die er hinzufügt, sind weiter unten in Wie der Broker Simpros Anmeldung aufwertet beschrieben.

Der Server sitzt vor Simpro und führt den Anmelde-Handshake aus. Ein Benutzer fügt den Connector in seinem Agenten hinzu, wird zu Simpro geschickt, um sich anzumelden, und von da an handelt der Agent als diese Person in Simpro. Ihr Simpro-Zugriff ist in dem Token versiegelt, das der Agent hält; der Server führt keine Datenbank mit Anmeldungen.

Dieser Modus benötigt eine öffentliche Webadresse und eine Simpro-OAuth-App (erstellt in Simpro unter Setup → Integrationen). Setzen Sie in dieser OAuth-App die Redirect-URL auf Ihre öffentliche Adresse gefolgt von /callback – zum Beispiel https://simpro.yourcompany.com/callback.

Einstellungen

Setzen Sie diese als Umgebungsvariablen, zusätzlich zu SIMPRO_BASE_URL (und optional SIMPRO_COMPANY_ID) von oben.

Setze SIMPRO_API_KEY in diesem Modus nicht – der Server weigert sich sonst zu starten.

3. HTTP-Proxy-Modus (für ein gemeinsames/gehostetes Setup)

Für Teams, die dies auf einem Server hinter etwas betreiben, das die Anmeldung bereits übernimmt (z. B. ein Cowork- oder Copilot-Setup). In diesem Modus hält der Server keinen eigenen Simpro-Schlüssel – jede Anfrage bringt ihre eigene Anmeldung mit, angehängt von dem, was deine Benutzer anmeldet. Der Server leitet sie nur an Simpro weiter.

⚠️ Nicht für den direkten Internetzugriff gedacht. Dieser Modus muss hinter einem Gateway oder Reverse-Proxy laufen (einem MCP-Gateway, Context Forge oder etwas wie nginx/Traefik), das TLS beendet und Benutzer authentifiziert. Er führt keine eigene Authentifizierung durch und ist nicht für direkte Exposition gehärtet – veröffentliche ihn niemals direkt im Internet. Der Container wird absichtlich standardmäßig nicht auf dem Host veröffentlicht; das Gateway erreicht ihn über ein privates Netzwerk.

Um diesen Modus zu nutzen, setze SIMPRO_TRANSPORT=proxy (das mitgelieferte Docker-Setup verwendet standardmäßig den sichereren Broker-Modus oben). Wenn du mit Portainer oder Context Forge bereitstellst, findest du das Stack-Layout in docs/deploy.md.

Du setzt hier keinen API-Schlüssel – tatsächlich weigert sich der Server zu starten, wenn einer vorhanden ist, denn in diesem Modus ist die benutzerspezifische Anmeldung das Einzige, was Zugriff gewähren soll.

Wichtig – dieser Modus führt keine eigene Prüfung durch. Was auch immer als Authorization-Header mit einer Anfrage eintrifft, wird unverändert direkt an Simpro weitergeleitet. Der Server prüft nicht, ob die Anmeldedaten gültig, nicht abgelaufen sind oder ob die Anfrage von jemandem stammt, der sie stellen darf – nur Simpro entscheidet, ob die Anmeldedaten funktionieren. Das ist beabsichtigt: Dieser Modus geht davon aus, dass die vorgelagerte Schicht (das Gateway oder Anmeldesystem) den Benutzer bereits authentifiziert und einen vertrauenswürdigen Header angehängt hat. Führe diesen Modus nur hinter einer solchen Schicht aus. Wenn du ihn direkt exponierst, kann jeder, der ihn erreicht, seinen Header unverändert an Simpro weiterleiten lassen.

Einstellungen

Diese werden als Umgebungsvariablen gesetzt (in deiner .env-Datei oder über deine Container-Plattform).

Setze SIMPRO_API_KEY in diesem Modus nicht – der Server weigert sich sonst zu starten.

Du kannst auch einstellen, wie viele Daten auf einmal zurückkommen:

4. Welchen Modus möchte ich?

5. Einen Client verbinden (Konfigurationsausschnitte)

Die Claude-Desktop-.mcpb-Installation (Option 1) schreibt ihre eigene Konfiguration – dafür musst du kein JSON anfassen. Diese Ausschnitte sind für das Ausführen aus einem Quellcode-Checkout oder das Ausrichten eines Clients auf einen gehosteten Broker/Proxy gedacht.

Claude Desktop – stdio aus dem Quellcode

Bearbeite claude_desktop_config.json (Einstellungen → Entwickler → Konfiguration bearbeiten). Richte command auf node und args auf das gebaute dist/index.js aus und übergib deine Simpro-Einstellungen als env:

{
  "mcpServers": {
    "simpro": {
      "command": "node",
      "args": ["/absolute/path/to/simpro-mcp/dist/index.js"],
      "env": {
        "SIMPRO_BASE_URL": "https://yourbuild.simprosuite.com",
        "SIMPRO_COMPANY_ID": "0",
        "SIMPRO_AUTH_MODE": "authorization_code",
        "SIMPRO_CLIENT_ID": "your-oauth-client-id",
        "SIMPRO_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

Zuerst bauen (npm install && npm run build). Unter Windows einen vollständigen Pfad mit maskierten Backslashes verwenden ("C:\\path\\to\\simpro-mcp\\dist\\index.js"). Für den Legacy-Schlüssel die Client-ID/das Client-Secret weglassen und stattdessen "SIMPRO_API_KEY" setzen (nur stdio).

Claude Code – claude mcp add

Denselben stdio-Server über die CLI registrieren (aus dem Checkout ausführen oder einen absoluten Pfad verwenden):

claude mcp add simpro \
  --env SIMPRO_BASE_URL=https://yourbuild.simprosuite.com \
  --env SIMPRO_COMPANY_ID=0 \
  --env SIMPRO_AUTH_MODE=authorization_code \
  --env SIMPRO_CLIENT_ID=your-oauth-client-id \
  --env SIMPRO_CLIENT_SECRET=your-oauth-client-secret \
  -- node ./dist/index.js

Einen Client auf einen gehosteten Broker ausrichten (Option 2)

Sobald der Broker hinter deiner öffentlichen Adresse läuft, füge ihn als Remote-Connector hinzu – es gibt keinen lokalen Befehl und keine Env. Verwende die Connector-/„Custom-Connector hinzufügen“-Oberfläche in deinem Client und gib die MCP-URL an:

https://simpro.yourcompany.com/mcp

Der Client wird zu Simpro weitergeleitet, um sich anzumelden; sonst ist nichts weiter zu konfigurieren. (Der HTTP-Proxy aus Option 3 wird auf dieselbe Weise erreicht, erwartet aber, dass dein Gateway den Bearer-Token anhängt – er wird nicht als nackter Connector hinzugefügt.)

6. Wie der Broker Simpros Anmeldung aufwertet

Dieser Abschnitt ist für technisch Interessierte oder alle, die die Sicherheit des Connectors prüfen möchten. Du brauchst ihn nicht, um einen der drei Modi oben zu nutzen.

Moderne Agent-Connectors verbinden sich nur mit Autorisierungsservern, die die OAuth-2.1-Anforderungen erfüllen. Simpros OAuth unterstützt kein PKCE und unterstützt nicht die Client-Identitätsschemata, die diese Connectors verwenden. Statt Simpro um eine Änderung zu bitten, stellt sich der Broker als eigener konformer OAuth-2.1-Autorisierungsserver davor und leitet im Hintergrund still an Simpro weiter. Konkret fügt er hinzu:

• PKCE (S256), von uns erzwungen. Der verbindende Client muss eine Code-Challenge an /authorize senden und sie bei /token nachweisen; eine Abweichung wird abgelehnt. Simpro selbst macht kein PKCE, also ist der Broker die Partei, die es tatsächlich durchsetzt – und damit die Lücke bei gestohlenen Autorisierungscodes schließt, die reines 2.0 offen lässt.

• Moderne Client-Identität – kein gemeinsames Geheimnis im Client eingebettet. Der verbindende Client teilt dem Broker auf eine von zwei Standardarten mit, wer er ist, und der Broker akzeptiert, was der jeweilige Client verwendet:

  • CIMD (Client-ID-Metadaten-Dokument): Die client_id ist eine URL, die der Broker pro Anfrage abruft und validiert – sie muss selbstreferenziell sein und die exakte verwendete Redirect-Adresse auflisten. Es ist nichts vorregistriert. Der Abruf läuft hinter einem Anti-SSRF-Schutz, damit diese URL nicht zum Ausspähen des internen Netzwerks des Servers verwendet werden kann.

  • DCR (dynamische Client-Registrierung, RFC 7591): Ein Client kann POST /register aufrufen, um sich im Voraus eine eigene client_id zu erstellen. Der Broker bewirbt diesen Endpunkt in seinen Metadaten. Die Registrierung ist offen (keine Authentifizierung), also raten-/größenbegrenzt und entfernt bei Erreichen der Grenze die ältesten Einträge; registrierte Clients werden persistiert, sodass sie einen Neustart überleben. Ein Client kann sich als öffentlich (ohne Geheimnis) oder vertraulich registrieren (der Broker stellt ein Geheimnis aus und verlangt es dann beim Token-Schritt).

  In beiden Fällen erreicht die Identität des nachgelagerten Clients Simpro nie: Der Broker hält eine feste Simpro-Registrierung und leitet unter dieser weiter.

• Exakte Redirect-Übereinstimmung. Die Adresse, an die der Client zurückgesendet wird, muss mit der registrierten übereinstimmen, Zeichen für Zeichen – nicht nur „beginnt mit“.

• Kurzlebige, an die Zielgruppe gebundene Tokens. Das Token, das der Client erhält, wird vom Broker ausgestellt, mit einem Ablaufdatum versehen und an diesen spezifischen Server als Zielgruppe gebunden. Die echten Simpro-Tokens sind darin verschlüsselt (versiegelt). Der Broker führt keine Token-Datenbank – jedes Token ist in sich geschlossen – und das von ihm ausgestellte Refresh-Token hat eine auf 30 Tage begrenzte Lebensdauer, sodass ein geleaktes Token nicht unbegrenzt wiederverwendet werden kann. Die eine Ausnahme: Da Simpro Refresh-Tokens bei der Verwendung rotiert (jede Aktualisierung verbraucht das alte), hält der Broker das aktuelle Upstream-Refresh-Token pro Login nur im Speicher, für ein paar Minuten, damit ein Client, der eine Refresh-Antwort verliert, nicht gezwungen ist, sich erneut anzumelden. Es wird nie auf die Festplatte geschrieben; die nächste erfolgreiche Aktualisierung – die bestätigt, dass der Client jetzt das aktuelle Token hält – entfernt es, und ein Neustart oder ein paar Minuten Inaktivität löschen es.

Der Nettoeffekt: Der Agent spricht mit etwas, das wie ein sauberer, moderner OAuth-2.1-Anbieter aussieht, der Benutzer meldet sich weiterhin am echten Simpro-Bildschirm an, und die schwächeren Teile des Simpro-Ablaufs werden in der Mitte abgesichert. Der gesamte Austausch wird nur für die wenigen Sekunden, die der Handshake dauert, im Speicher korreliert, weshalb dieser Modus als Einzelinstanz laufen muss – nicht hinter einem Load Balancer platzieren.

Selbst bauen

Wenn du am Code arbeitest und ihn nicht nur verwendest:

npm install
npm run build        # compile
npm test             # run the unit tests
npm run login        # one-time browser sign-in (authorization_code); caches the refresh token
npm run build:mcpb   # produce the simpro-mcp-server.mcpb install file
npm start            # run it locally

npm run login führt das kompilierte dist/login.js aus, also erst bauen; es benötigt SIMPRO_CLIENT_ID und SIMPRO_CLIENT_SECRET (siehe Lokal aus dem Quellcode ausführen oben).

Es gibt eine Unit-Test-Suite (npm test), die die reinen, deterministischen Teile abdeckt – Suchranking, Ausgabeformatierung, Positionspfade und die Auth-Krypto-/Speicher-Helfer. Es gibt keinen Linter und nichts, das das Netzwerk mockt, daher bedeutet eine vollständige Überprüfung einer Änderung weiterhin, sie zu bauen und gegen ein echtes Simpro-Konto zu testen. Architekturnotizen und die wissenswerten Eigenheiten der Simpro-API findest du in CLAUDE.md.