Gosar MCP Server

Ein MCP-Server, der es Claude ermöglicht, die Gosar-API im Namen eines Benutzers aufzurufen, authentifiziert über Gosars OAuth-2.0- und PKCE-Flow.

Es fungiert als Brücke:

• Gegenüber Claude (dem MCP-Client) verhält es sich wie ein vollwertiger OAuth-Autorisierungsserver – er übernimmt die dynamische Client-Registrierung und gibt eigene kurzlebige Tokens aus.

• Gegenüber Gosar ist es der einzige, vorregistrierte OAuth-Client (öffentlich, nur PKCE), der den tatsächlichen Authorization-Code- und PKCE-Austausch durchführt, wie in Gosars Integrationsleitfaden beschrieben.

Voraussetzungen

• Python 3.11+

• Ein bei Gosar registrierter OAuth-Client (siehe „Was wir von dir brauchen“ im Integrationsleitfaden) – du benötigst eine client_id und eine genehmigte Redirect-URI.

• ngrok (oder Ähnliches), wenn du gegen die echte Gosar-API testen möchtest – Gosars Redirect-URI muss HTTPS sein und exakt übereinstimmen, und Claude benötigt ebenfalls eine HTTPS-URL, um einen entfernten MCP-Server zu verbinden.

Related MCP server: Strava MCP Server

1. Abhängigkeiten installieren

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. .env konfigurieren

Kopiere die vorhandenen Werte in .env im Projektstammverzeichnis:

# Real values from the Gosar team
GOSAR_API_BASE_URL=https://api.gosar.example
GOSAR_CLIENT_ID=your-registered-client-id
GOSAR_SCOPES=applications.read applications.write

# Your server's own public HTTPS URL (e.g. your ngrok URL). Gosar's registered
# redirect_uri must be exactly this + GOSAR_REDIRECT_PATH.
MCP_PUBLIC_BASE_URL=https://your-tunnel.ngrok-free.app
GOSAR_REDIRECT_PATH=/gosar/callback

MCP_HOST=0.0.0.0
MCP_PORT=8000

# Generate once and keep stable — see below
JWT_SIGNING_KEY=

Generiere einen Signaturschlüssel (Gosar ist ein öffentlicher Client ohne Geheimnis, daher kann dieser nicht automatisch abgeleitet werden – er ist erforderlich):

python -c "import secrets; print(secrets.token_urlsafe(32))"

Füge die Ausgabe in JWT_SIGNING_KEY ein. Behalte ihn über Neustarts hinweg bei, sonst werden alle verbundenen Benutzer abgemeldet.

3. Server über HTTPS bereitstellen (für echte Gosar-Tests)

Claude und Gosar erfordern beide HTTPS. In einem separaten Terminal:

ngrok http 8000

Kopiere die https://...ngrok-free.app-URL in MCP_PUBLIC_BASE_URL in .env und sende {MCP_PUBLIC_BASE_URL}/gosar/callback als deine registrierte Redirect-URI an das Gosar-Team.

4. Server ausführen

source .venv/bin/activate
python main.py

Du solltest Folgendes sehen:

Starting MCP server 'Gosar' with transport 'http' on http://0.0.0.0:8000/mcp
Uvicorn running on http://0.0.0.0:8000

Automatisches Neuladen bei Codeänderungen

python main.py lädt nicht neu – mcp.run() blockiert und besitzt einen eigenen uvicorn-Prozess, der nicht an einen dateiüberwachenden Reloader übergeben werden kann. Für die Entwicklung führe stattdessen die ASGI-App in gosar_mcp/asgi.py direkt unter uvicorn aus:

uvicorn gosar_mcp.asgi:app --reload --reload-include ".env" --host 0.0.0.0 --port 8000

• --reload startet den Worker-Prozess neu, wenn sich eine .py-Datei ändert.

• --reload-include ".env" startet ihn auch neu, wenn du .env bearbeitest (uvicorn überwacht standardmäßig nur Python-Dateien, und Umgebungsvariablen werden nur einmal beim Prozessstart gelesen, daher ist ohne dieses Flag ein manueller Neustart erforderlich).

• Halte den Port mit dem Ziel deines ngrok-Tunnels synchron.

5. OAuth-Verkabelung überprüfen

Bei laufendem Server bestätige, dass die Discovery-Metadaten bereitgestellt werden:

curl -s http://127.0.0.1:8000/.well-known/oauth-authorization-server | python3 -m json.tool

Du solltest applications.read/applications.write in scopes_supported und S256 als einzige PKCE-Methode sehen.

6. Mit Claude verbinden

Füge in den Connector-Einstellungen von Claude einen entfernten MCP-Server hinzu, der auf Folgendes zeigt:

https://your-tunnel.ngrok-free.app/mcp

Claude registriert sich selbst als OAuth-Client bei diesem Server, leitet den Benutzer durch die Zustimmung, dann durch Gosars echten Google-Anmelde- und Zustimmungsbildschirm, und kehrt mit einer aktiven Verbindung hierher zurück. Bitte Claude, das whoami-Tool aufzurufen, um zu bestätigen, dass es als das erwartete Gosar-Konto authentifiziert ist.

Hinweise

• Die Token-Speicherung (Client-Registrierungen + verschlüsselte Upstream-Gosar-Tokens) verwendet standardmäßig einen betriebssystemgerechten verschlüsselten Dateispeicher auf der Festplatte – keine zusätzliche Einrichtung für die lokale Entwicklung erforderlich. Siehe gosar_mcp/auth.py für die Konfiguration eines anderen Backends in der Produktion.

• Die /applications-Endpunktpfade in gosar_mcp/tools.py sind Platzhalter – der Integrationsleitfaden spezifiziert nur die OAuth-Schicht, nicht die Form der Applications-REST-API. Bestätige die tatsächlichen Pfade/Payloads mit dem Gosar-Team und passe sie dort an.