Skip to main content Skip to page footer

Claude Desktop

Claude Desktop läuft lokal auf macOS, Windows oder Linux. Die Verbindung zum MCP-Server wird von deinem Rechner aus aufgebaut, nicht von Anthropics Infrastruktur. Der MCP-Server muss daher nicht öffentlich erreichbar sein. Es funktionieren localhost, *.ddev.site, interne DNS-Namen und selbstsignierte Zertifikate, solange dein Betriebssystem der ausstellenden CA vertraut.

Zur Authentifizierung empfiehlt sich für Claude Desktop ein statisches Bearer-Token, das im AI Suite-Backend erzeugt wird. Das ist der einfachste Weg und kommt ohne OAuth-Einrichtung aus. Alternativ ist der OAuth-Flow möglich (identisch zu Claude.ai). Läuft TYPO3 auf demselben Rechner, gibt es zusätzlich einen lokalen stdio-Modus (siehe vollständiger Guide).

Voraussetzungen

  • enableMcp ist aktiviert (siehe Konfiguration).
  • mcpAllowHttp nur dann auf 1, wenn die TYPO3-URL reines HTTP ist (lokale Entwicklung ohne TLS). In der Produktion bleibt der Wert 0.
  • Die Backend-Gruppe besitzt enable_mcp_access und die benötigten Feature-Rechte (siehe Berechtigungen & Scopes).
  • Der TYPO3-Host ist von deinem Rechner aus erreichbar. Ein Aufruf von [typo3-url]/aisuite-mcp/health muss 200 liefern. Bei selbstsigniertem Zertifikat (z. B. DDEV) die CA im System hinterlegen (mkcert -install).
  • Claude Desktop ist installiert. Lokale MCP-Server funktionieren auch im kostenlosen Plan.

Verbindung einrichten

1. Token erstellen. Öffne im AI Suite-Backend-Modul den Tab MCP und klicke auf Create Token. Es wird ein an deinen Backend-Benutzer gebundenes Token mit allen Scopes erzeugt, zu denen du berechtigt bist. Kopiere den angebotenen claude_desktop_config.json-Ausschnitt. Die Gültigkeit steuert mcpTokenLifetimeDays (Standard 30).

{
  "mcpServers": {
    "typo3-ai-suite": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "[typo3-url]/aisuite-mcp",
        "--header",
        "Authorization: Bearer [token]"
      ]
    }
  }
}

Warum ein Befehl und keine URL? Die claude_desktop_config.json nimmt ausschließlich stdio-Server an, also command, args und env. Ein Eintrag mit url und headers führt dazu, dass Claude Desktop die MCP-Server als fehlkonfiguriert meldet. Die Brücke mcp-remote läuft deshalb lokal und leitet mit angehängtem Bearer-Token an den HTTP-Endpoint weiter. Sie braucht Node.js in Version 18 oder neuer auf dem Rechner, auf dem Claude Desktop läuft. Wer ohne Brücke arbeiten will, hat zwei Alternativen: den Custom Connector per OAuth (siehe unten) oder den lokalen stdio-Transport.

2. Snippet einfügen. Trage den Ausschnitt in die Konfigurationsdatei von Claude Desktop ein. Vorhandene Einträge unter mcpServers nicht überschreiben, sondern ergänzen. Danach Claude Desktop vollständig beenden und neu starten (Fenster schließen genügt nicht).

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

3. Verbindung prüfen. Öffne eine neue Unterhaltung und das Tools-/Connector-Menü unter dem Eingabefeld. Unter dem Servereintrag typo3-ai-suite sollten die AI Suite-Tools erscheinen (readServerInfo, listTables, readPageTree usw.). Die Tools müssen pro Chat aktiviert sein.

Selbstsignierte Zertifikate (DDEV, mkcert)

Das ist der häufigste Stolperstein bei lokalen Setups mit DDEV oder mkcert. mkcert -install legt die CA in den Trust-Store des Betriebssystems, was für Browser und curl reicht. Node.js ignoriert diesen Store und bringt einen eigenen CA-Vorrat mit. Die Brücke scheitert deshalb mit UNABLE_TO_VERIFY_LEAF_SIGNATURE, obwohl dieselbe URL im Browser mit 200 antwortet.

Die Lösung ist ein env-Block im selben Servereintrag, der Node.js auf die mkcert-Wurzel zeigt. Das Verzeichnis nennt dir mkcert -CAROOT.

{
  "mcpServers": {
    "typo3-ai-suite": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "[typo3-url]/aisuite-mcp", "--header", "Authorization: Bearer [token]"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "[mkcert -CAROOT]/rootCA.pem"
      }
    }
  }
}

Prüfe das am besten erst außerhalb von Claude Desktop:

NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" \
  node -e "require('https').get('[typo3-url]/aisuite-mcp/health', r => console.log(r.statusCode))"

Genau daran liegt es, wenn ein *.ddev.site-Host für Claude Desktop unerreichbar wirkt. Ein Tunnel über cloudflared oder ngrok ist nicht nötig, die Brücke löst lokale Hostnamen problemlos auf.

Troubleshooting

  • Server fehlt in der Tool-Liste: Die claude_desktop_config.json hat einen JSON-Syntaxfehler oder liegt im falschen Pfad. Datei prüfen (z. B. python -m json.tool) und Pfad gegen die Liste oben abgleichen.
  • Claude Desktop meldet die MCP-Server als fehlkonfiguriert: Der Servereintrag enthält url, transport oder headers statt command und args. Ältere Versionen des MCP-Dashboards haben an dieser Stelle die HTTP-Form ausgegeben. Token neu erzeugen, um das aktuelle Snippet zu erhalten, oder auf Custom Connector beziehungsweise lokalen stdio-Transport wechseln.
  • npx: command not found oder der Eintrag bleibt in der Tool-Liste grau: Die Brücke mcp-remote braucht Node.js auf dem Rechner mit Claude Desktop, und GUI-Programme starten mit einem sehr kurzen PATH. Node.js ab Version 18 installieren oder "npx" durch den absoluten Pfad ersetzen, etwa /usr/local/bin/npx. Vorher die Brücke von Hand testen.
  • 401 oder „Authentication required“: Token ungültig, abgelaufen oder widerrufen, oder die URL enthält ein Site-Präfix. Token neu erzeugen und die Root-URL [typo3-url]/aisuite-mcp verwenden.
  • SSL-Zertifikatsfehler, etwa UNABLE_TO_VERIFY_LEAF_SIGNATURE: Selbstsigniertes Zertifikat. Ein mkcert -install allein genügt für die Brücke nicht, weil Node.js einen eigenen CA-Vorrat mitbringt und den System-Trust-Store ignoriert. Siehe den Abschnitt zu selbstsignierten Zertifikaten.
  • Model meldet „kein MCP-Zugriff“: Die AI Suite-Tools sind im Chat nicht aktiviert. Im Tools-/Connector-Menü einschalten.

Allgemeine Fehlerquellen (Authorization-Header, leere Tool-Liste, deaktivierter Endpoint) sind unter Sicherheit & Betrieb beschrieben. Die ausführliche Anleitung steht im Connector-Guide im Repository.

Alternative: Custom Connector (OAuth statt statisches Token)

Claude Desktop kann einen entfernten MCP-Server auch ganz ohne Konfigurationsdatei ansprechen, über Einstellungen, Connectors, Add custom connector. Dort trägst du die Server-URL [typo3-url]/aisuite-mcp ein und bestätigst. Claude Desktop führt dann den OAuth-2.1-Ablauf gegen den MCP-Server durch, inklusive dynamischer Client-Registrierung, und verwaltet die Tokens selbst.

Zwei Unterschiede zum Weg über das Token:

  • Keine eigenen Header. Die Connector-Oberfläche hat kein Header-Feld, das statische Bearer-Token lässt sich hier also nicht verwenden. Authentifiziert wird ausschließlich per OAuth, weshalb mcpAllowedRedirectUris und mcpAllowedOrigins gefüllt sein müssen. Die Werte sind dieselben wie bei Claude.ai.
  • Kein Node.js nötig, weil lokal nichts gestartet wird.

Die Verbindung geht weiterhin von deinem Rechner aus. Localhost, *.ddev.site und interne Hosts bleiben also erreichbar.