# Claude mit microtech GraphQL verbinden (MCP)

<span class="custom-button red-button">Gen. 24 Enterprise</span>

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 ![Alt-Text](https://assets.hilfe.microtech.de/bilder/18_graphql/graphqlclaudemcp_1.png)

!!! 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 büro+

*    **GraphQL-Server** ist eingerichtet und läuft (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...` |

!!! 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.

![Alt-Text](https://assets.hilfe.microtech.de/bilder/18_graphql/graphqlclaudemcp_2.png)

*    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

<div class="video-consent" data-videoid="t9HFIG3EFSU">
  <img src="https://img.youtube.com/vi/t9HFIG3EFSU/maxresdefault.jpg" alt="Video Vorschau">
  <div class="play-button">▶ Video abspielen</div>
  <div class="privacy-note">
    Beachten Sie: Durch den Klick auf das Bild wird das Video geladen und Daten an YouTube übertragen.<br>
    <a href="https://www.microtech.de/datenschutz/">Mehr Infos</a>
  </div>
</div>

## Weiterführende Dokumentation

- [OAuth 2.0 API-Dokumentation](../18_graphql/oauthapidoku.md)
- [Bearer Token Generator](../18_graphql/graphqlbearertokengenerator.md)
- [GraphQL Entwickler Dokumentation](../18_graphql/graphqldoku.md)
- [GraphQL Beispiel-Queries](../18_graphql/graphqlbeispielqueries.md)
- [Offizielle MCP-Dokumentation (Englisch)](https://docs.claude.com/de/docs/claude-code/mcp) (Externer Link)
