# Claude mit microtech GraphQL verbinden (MCP)
Gen. 24 Enterprise
Diese Anleitung zeigt Schritt für Schritt, wie Sie Claude (Desktop oder Code) mit der microtech GraphQL-Schnittstelle verbinden. Damit kann Claude direkt auf Ihre microtech-Daten zugreifen und Abfragen ausführen.
!!! tip "Tipp"
Die auf dieser Seite gezeigten Code-Beispiele lassen sich direkt über das nebenstehende Symbol kopieren 
!!! info "Info"
**Was ist MCP?**
MCP (Model Context Protocol) ist eine Erweiterung, die es Claude ermöglicht, auf externe Datenquellen zuzugreifen. Mit dem GraphQL-MCP kann Claude direkt Daten aus Ihrer microtech Software abfragen.
## Voraussetzungen
Bevor Sie beginnen, stellen Sie sicher, dass folgende Voraussetzungen erfüllt sind:
### In microtech ERP
* **GraphQL-Zugriff** ist eingerichtet - automatisch je Mandant (siehe [GraphQL-Endpunkt](../18_graphql/graphqlendpunkteinrichten.md)) oder manuell über einen Automatisierungsdienst (siehe [GraphQL Entwickler Dokumentation](../18_graphql/graphqldoku.md#13-einrichtung-und-verwendung-des-graphql-servers))
* **OAuth-Anwendung** ist angelegt (siehe [OAuth 2.0 API-Dokumentation - Anwendung einrichten](../18_graphql/oauthapidoku.md#2-anwendung-einrichten-oauth-client))
* **Bearer Token** wurde generiert (siehe [Bearer Token Generator](../18_graphql/graphqlbearertokengenerator.md))
* Der Benutzer hat das Kennzeichen **"Zugriff über GraphQL erlaubt"** aktiviert
### Auf Ihrem Computer
* **Node.js** ist installiert (für Claude Desktop und Claude Code erforderlich)
---
## Teil A: Einrichtung für Claude Desktop
Claude Desktop ist die grafische Anwendung für Windows und macOS.
### Schritt 1: Node.js installieren
Node.js wird benötigt, um das GraphQL-MCP auszuführen.
1. Öffnen Sie [https://nodejs.org/](https://nodejs.org/) (Externer Link)
2. Laden Sie die **LTS-Version** (Long Term Support) herunter
3. Führen Sie das Installationsprogramm aus und folgen Sie den Anweisungen
**Prüfen Sie die Installation:** Öffnen Sie die Eingabeaufforderung (Windows-Taste + R, dann `cmd` eingeben) und geben Sie ein:
```
node --version
```
Es sollte eine Versionsnummer angezeigt werden (z.B. `v20.10.0`).
### Schritt 2: Claude Desktop herunterladen und installieren
1. Öffnen Sie [https://claude.ai/download](https://claude.ai/download) (Externer Link)
2. Laden Sie Claude Desktop für Ihr Betriebssystem herunter
3. Installieren Sie die Anwendung
### Schritt 3: Konfigurationsdatei erstellen
Die MCP-Konfiguration wird in einer JSON-Datei gespeichert.
1. Öffnen Sie den Datei-Explorer (z. B. durch Drücken von Windows-Taste + E auf der Tastatur)
2. Geben Sie in die Adressleiste ein: `%APPDATA%\Claude\` und drücken Sie Enter
3. Falls der Ordner nicht existiert, starten Sie Claude Desktop einmal und schließen Sie es wieder
4. Erstellen Sie eine neue Textdatei mit dem Namen `claude_desktop_config.json`
!!! warning "Beachten Sie"
**Dateiendung beachten!**
Stellen Sie sicher, dass die Datei tatsächlich `.json` als Endung hat und nicht `.json.txt`. Aktivieren Sie ggf. unter "Ansicht" die Option "Dateinamenerweiterungen" im Windows Explorer.
### Schritt 4: Konfiguration einfügen
Öffnen Sie die Datei `claude_desktop_config.json` mit einem Texteditor (z.B. Notepad) und fügen Sie folgenden Inhalt ein:
```json
{
"mcpServers": {
"mcp-graphql": {
"command": "npx",
"args": ["mcp-graphql"],
"env": {
"ENDPOINT": "https://IHR-SERVER.domain.de:443/microtech/erp/IHRE-GRAPHQL-ID/graphql/v1",
"NODE_TLS_REJECT_UNAUTHORIZED": "0",
"ALLOW_MUTATIONS": "true",
"HEADERS": "{\"Authorization\": \"Bearer IHR-BEARER-TOKEN\"}"
}
},
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"]
}
}
}
```
!!! info "Info"
**Was ist Playwright?**
Playwright ermöglicht es Claude, Webseiten zu öffnen und zu analysieren. Damit kann Claude z.B. die Online-Dokumentation direkt lesen und Ihnen bei Fragen helfen.
**Passen Sie folgende Werte an:**
| Platzhalter | Ersetzen durch | Beispiel |
|-------------|----------------|----------|
| `IHR-SERVER.domain.de` | Ihre Server-Adresse | `erp.meinefirma.de` |
| `IHRE-GRAPHQL-ID` | Die ID Ihres GraphQL-Servers | `5060B010FC9873EDAF2C79C7E8DB879B` |
| `IHR-BEARER-TOKEN` | Ihr generiertes Bearer Token | `nhe0hVg2blBOrtleMpRwhwnnH...` |
!!! info "Info"
Nutzen Sie den automatischen GraphQL-Endpunkt, ersetzen Sie `IHRE-GRAPHQL-ID` durch `mand/` - siehe [GraphQL-Endpunkt - URL-Struktur](../18_graphql/graphqlendpunkteinrichten.md#3-url-struktur).
!!! tip "Tipp"
**Bearer Token generieren**
Nutzen Sie den [Bearer Token Generator](../18_graphql/graphqlbearertokengenerator.md), um aus Client-ID und Client-Secret ein Bearer Token zu erhalten.
### Schritt 5: Claude Desktop neu starten
* Schließen Sie Claude Desktop vollständig (auch aus dem System-Tray mit der rechten Maustaste und ... beenden). Den System-Tray finden Sie in der Taskleistenecke.
* Starten Sie Claude Desktop erneut
* Beim ersten Start wird das MCP-Paket automatisch heruntergeladen
### Schritt 6: Verbindung testen
Geben Sie in Claude Desktop folgende Nachricht ein:
```
Liste mir die Adressen mit Hilfe des GraphQL MCP auf und zeige mir die Daten in Tabellenform an.
```
Wenn alles korrekt eingerichtet ist, sollte Claude nun Daten aus Ihrer microtech Software abrufen und anzeigen.
---
## Teil B: Einrichtung für Claude Code
Claude Code ist das Kommandozeilen-Tool für Entwickler. Die Einrichtung erfordert zusätzliche Software.
### Schritt 1: Erforderliche Software installieren
#### Git installieren
Git wird für die Installation von Claude Code benötigt.
1. Öffnen Sie [https://git-scm.com/download/win](https://git-scm.com/download/win) (Externer Link)
2. Laden Sie die 64-bit Version herunter
3. Führen Sie das Installationsprogramm aus
4. Übernehmen Sie die Standardeinstellungen
**Prüfen Sie die Installation:**
```
git --version
```
#### Node.js installieren
Falls noch nicht geschehen (siehe Teil A, Schritt 1):
1. Öffnen Sie [https://nodejs.org/](https://nodejs.org/)
2. Laden Sie die **LTS-Version** herunter
3. Führen Sie das Installationsprogramm aus
**Prüfen Sie die Installation:**
```
node --version
npm --version
```
#### Python installieren (optional, aber empfohlen)
Einige MCP-Erweiterungen benötigen Python.
1. Öffnen Sie [https://www.python.org/downloads/](https://www.python.org/downloads/) (Externer Link)
2. Laden Sie die aktuelle Version herunter
3. **Wichtig:** Aktivieren Sie beim Installieren die Option "Add Python to PATH"
**Prüfen Sie die Installation:**
```
python --version
```
### Schritt 2: Claude Code installieren
Öffnen Sie eine Eingabeaufforderung (cmd) oder PowerShell und führen Sie aus:
```
npm install -g @anthropic-ai/claude-code
```
**Prüfen Sie die Installation:**
```
claude --version
```
!!! warning "Beachten Sie"
Wie ist vorzugehen, wenn 'claude' nicht gefunden wird?
Wenn die Fehlermeldung erscheint, dass `claude` nicht erkannt wird, fehlt der npm-Pfad in den Umgebungsvariablen.
**Lösung:**
1. Drücken Sie `Windows-Taste + R` und geben Sie `sysdm.cpl` ein
2. Wechseln Sie zum Tab **Erweitert**
3. Klicken Sie auf **Umgebungsvariablen**
4. Unter **Benutzervariablen** wählen Sie **Path** und klicken auf **Bearbeiten**
5. Klicken Sie auf **Neu** und fügen Sie folgenden Pfad hinzu:
```
%USERPROFILE%\AppData\Roaming\npm
```
6. Bestätigen Sie alle Dialoge mit **OK**
7. **Schließen Sie die Eingabeaufforderung und öffnen Sie eine neue** (wichtig!)
8. Prüfen Sie erneut mit `claude --version`
### Schritt 3: MCPs hinzufügen
#### GraphQL-MCP hinzufügen
Führen Sie folgenden Befehl aus (alles in einer Zeile):
```
claude mcp add --scope user mcp-graphql -e ENDPOINT=https://IHR-SERVER.domain.de:443/microtech/erp/IHRE-GRAPHQL-ID/graphql/v1 -e NODE_TLS_REJECT_UNAUTHORIZED=0 -e ALLOW_MUTATIONS=true -e HEADERS="{\"Authorization\": \"Bearer IHR-BEARER-TOKEN\"}" -- cmd /c npx mcp-graphql
```
**Passen Sie die Werte an** (siehe Tabelle in Teil A, Schritt 4).
#### Playwright-MCP hinzufügen
Playwright ermöglicht es Claude, Webseiten zu öffnen und zu analysieren:
```
claude mcp add --scope user playwright -- cmd /c npx @playwright/mcp@latest
```
!!! info "Scope-Option"
Die Option `--scope user` macht das MCP für alle Ihre Projekte verfügbar. Alternativen:
- `--scope local` - Nur im aktuellen Projekt
- `--scope project` - Geteilt mit allen im Projekt (über `.mcp.json` Datei)
### Schritt 4: Installation prüfen
Prüfen Sie, ob das MCP korrekt installiert wurde:
```
claude mcp list
```
Sie sollten `mcp-graphql` in der Liste sehen.
### Schritt 5: Claude Code starten und testen
Starten Sie Claude Code:
```
claude
```
Geben Sie dann folgende Nachricht ein:
```
Liste mir die Adressen mit Hilfe des GraphQL MCP auf und zeige mir die Daten in Tabellenform an.
```
---
## Tipps für die Verwendung
### Das GraphQL-Schema ist sehr groß
Das microtech GraphQL-Schema enthält viele Tabellen und Felder. Damit Claude nicht das gesamte Schema auf einmal laden muss, verwenden Sie gezielte Anweisungen:
```
Lies zunächst die folgenden Dokumentationen, um die GraphQL-Schnittstelle zu verstehen:
* https://hilfe.microtech.de/18_graphql/graphqldoku/index.md
* https://hilfe.microtech.de/18_graphql/graphqlmutations/index.md
* https://hilfe.microtech.de/18_graphql/graphqlbeispielqueries/index.md
* https://hilfe.microtech.de/18_graphql/graphqlvorgangexternebearbeitung/index.md
* https://hilfe.microtech.de/18_graphql/graphqlvorgangfunktionsreferenz/index.md
Danach verwende das MCP GraphQL-Tool, um das Schema schrittweise zu erkunden:
1. **Tabellenliste abrufen:**
Query: { __type(name: "Query") { fields { name description } } }
2. **Für jede angefragte Tabelle - Namenskonvention beachten:**
- `tblAddresses` (Query-Level) → `AddressesTableQueryRead` (Table-Type) → `AddressRowQueryRead` (Row-Type)
- Muster: `tbl{Name}` → `{Name}TableQueryRead` → `{SingularName}RowQueryRead`
3. **Felder einer Tabelle ermitteln (zweistufig):**
* a. Erst Table-Type abfragen: __type(name: "{Name}TableQueryRead") { fields { name type { name kind } } }
* b. Dann Row-Type abfragen: __type(name: "{Name}RowQueryRead") { fields { name description type { name kind } } }
4. **Für Relationen (row{Field}) separate Introspection:**
Wenn du z.B. rowReAnsNr siehst (Typ: PostalAddressRowQueryRead), musst du auch PostalAddressRowQueryRead separat abfragen, um dessen Felder zu kennen.
**Wichtig:**
* NIEMALS die volle Schema-Introspection (`introspect-schema`) aufrufen - das erzeugt 9MB+ Daten
* Die Dokumentation enthält KEINE konkreten Feldnamen - du musst Introspection nutzen
* Feldpräfixe: `fld...` = Datenfelder, `row...` = 1:1 Relationen, `tbl...` = 1:n Relationen, `lnk...` = Links
Warte nach der Initialisierung auf meine Angaben, welche Tabelle ich abfragen möchte.
```
### Empfohlenes KI-Modell
Für komplexe GraphQL-Abfragen empfehlen wir, in Claude das Modell **Opus** zu verwenden, da es komplexere Zusammenhänge besser versteht.
### Berechtigungen einschränken
Aus Sicherheitsgründen sollten Sie:
* Einen eigenen ERP-Benutzer für GraphQL-Zugriffe anlegen
* Die Berechtigungen auf die benötigten Bereiche einschränken
* Das Bearer Token mit angemessener Gültigkeitsdauer erstellen
---
## MCP aktualisieren oder entfernen
### MCP entfernen
**Claude Code:**
```
claude mcp remove mcp-graphql
```
**Claude Desktop:** Löschen Sie den entsprechenden Eintrag aus der `claude_desktop_config.json`.
### MCP mit neuen Einstellungen aktualisieren
Um Einstellungen wie ENDPOINT oder Bearer Token zu ändern:
1. Entfernen Sie das MCP (siehe oben)
2. Fügen Sie es mit den neuen Einstellungen wieder hinzu
---
## Fehlerbehebung
### "Node nicht gefunden" oder "npx nicht erkannt"
* Stellen Sie sicher, dass Node.js installiert ist
* Starten Sie die Eingabeaufforderung/Claude neu nach der Installation
* Prüfen Sie, ob Node.js im PATH ist: `echo %PATH%` (Windows)
### Verbindung zum GraphQL-Server schlägt fehl
* Prüfen Sie, ob der GraphQL-Server läuft
* Prüfen Sie die URL (HTTPS, Port, Pfad)
* Prüfen Sie, ob das Bearer Token gültig ist
* Bei selbstsignierten Zertifikaten: `NODE_TLS_REJECT_UNAUTHORIZED=0` ist gesetzt
### Bearer Token abgelaufen
Generieren Sie ein neues Token mit dem [Bearer Token Generator](../18_graphql/graphqlbearertokengenerator.md) und aktualisieren Sie die Konfiguration.
### Claude Desktop zeigt MCP nicht an
* Prüfen Sie, ob die JSON-Datei syntaktisch korrekt ist (keine fehlenden Kommas, Anführungszeichen)
* Nutzen Sie einen JSON-Validator: [https://jsonlint.com/](https://jsonlint.com/) (Externer Link)
* Starten Sie Claude Desktop neu
---
### KI ohne MCP-Anbindung an microtech Software als Hilfsmittel verwenden
▶ Video abspielen
Beachten Sie: Durch den Klick auf das Bild wird das Video geladen und Daten an YouTube übertragen. Mehr Infos
