strava-openapi-mcp

Lokaler Python-MCP-Server, der als generischer Proxy zwischen einem MCP-Client – insbesondere OpenCode – und der Strava-REST-API fungiert. Die Tools werden nicht Endpunkt für Endpunkt implementiert: Sie werden beim Start aus der offiziellen Swagger-2.0-Spezifikation von Strava generiert.

Das Repository enthält eine Kopie der Spezifikation und der referenzierten Schema-Dokumente. Der Start benötigt daher keinen Internetzugriff, um die Tool-Liste zu erstellen. Der Befehl update-spec aktualisiert die lokale Kopie nach der Validierung.

Architektur

openapi.py lädt und validiert Swagger, löst lokale Referenzen auf und normalisiert Operationen. tools.py transformiert jede Operation in ein MCP-Tool mit einem generierten JSON-Schema. client.py erstellt URLs, Parameter, JSON-Bodies und Multipart-Formulare, ohne die Strava-Endpunkte einzeln zu kennen. auth.py übernimmt den lokalen OAuth-Ablauf und die Token-Erneuerung. server.py stellt alles über MCP stdio bereit, während cli.py Wartungsbefehle bereitstellt.

Die derzeit veröffentlichte Spezifikation von Strava ist Swagger 2.0, mit info.version 3.0.0. Das Bundle wird bewusst als austauschbare Daten behandelt: Wenn ein neuer Endpunkt in der Spezifikation erscheint, wird er automatisch erkannt.

Related MCP server: MCP OpenAPI Connector

Voraussetzungen und lokale Installation

Python 3.12+ und uv werden empfohlen.

git clone https://github.com/Arbodgad/strava-openapi-mcp.git
cd strava-openapi-mcp
uv sync
uv run strava-mcp list-tools

Starten Sie den MCP-Server mit:

uv run strava-mcp

Der Server bleibt auf dem MCP-stdin/stdout-Transport aktiv. Anwendungsprotokolle werden an stderr gesendet. Während des stdio-Transports darf kein Diagnoseprotokoll auf stdout geschrieben werden.

Eine Strava-Anwendung erstellen

1. Öffnen Sie https://www.strava.com/settings/api.

2. Erstellen Sie eine Anwendung und notieren Sie sich Client ID und Client Secret.

3. Strava akzeptiert localhost und 127.0.0.1 als Callback-Domains. Der Standard-Callback ist http://127.0.0.1:8765/callback.

Anmeldedaten können über die Umgebung bereitgestellt werden:

export STRAVA_CLIENT_ID="..."
export STRAVA_CLIENT_SECRET="..."

Oder in ~/.config/strava-mcp/credentials.json mit 0600-Berechtigungen:

{
  "client_id": "...",
  "client_secret": "..."
}

Umgebungsvariablen haben Vorrang. Das Secret wird niemals angezeigt oder in Protokollen geschrieben.

OAuth

Einmal ausführen:

strava-mcp auth

Der Browser öffnet die Strava-Autorisierungsseite. Der lokale Callback tauscht den Autorisierungscode gegen access_token, refresh_token, expires_at und die gewährten Scopes aus. Die Tokens werden in ~/.config/strava-mcp/tokens.json mit 0600-Berechtigungen gespeichert. Der Server erneuert automatisch abgelaufene Zugriffstokens und speichert ein rotierendes Refresh-Token, wenn Strava eines zurückgibt.

Standardmäßig werden alle in der Spezifikation deklarierten Scopes angefordert. Um eine Teilmenge anzufordern:

export STRAVA_OAUTH_SCOPES="activity:read,activity:write"

Offizielle Beschreibungen werden analysiert, um explizite Scopes abzuleiten. Lese-Endpunkte, die entweder activity:read oder activity:read_all akzeptieren, werden als Alternativen dargestellt. Ein bedingter Scope – wie activity:read_all für eine private Aktivität – wird dem LLM angezeigt, und die ursprüngliche Strava-Fehlermeldung bleibt sichtbar.

Konfiguration

Unterstützte Variablen:

Die Aliase STRAVA_MCP_ALLOW_WRITE und STRAVA_MCP_ALLOW_DELETE werden ebenfalls akzeptiert. strava-mcp show-config zeigt nur eine nicht-sekrete Konfigurationsansicht.

Die empfohlenen Werte sind STRAVA_ALLOW_WRITE=true und STRAVA_ALLOW_DELETE=false. POST-, PUT- und PATCH-Methoden werden standardmäßig nicht blockiert. DELETE-Methoden werden generiert, wenn die Spezifikation sie enthält, aber aus der MCP-Tool-Liste gefiltert, solange STRAVA_ALLOW_DELETE=false ist.

Erster Start

export STRAVA_CLIENT_ID="..."
export STRAVA_CLIENT_SECRET="..."
strava-mcp auth
strava-mcp list-tools
strava-mcp

Die lokale Spezifikationskopie hat Vorrang. Wenn sie nicht existiert, wird die gebündelte offizielle Spezifikation verwendet, ohne beim Start etwas herunterzuladen.

Spezifikation aktualisieren

strava-mcp update-spec

Der Befehl lädt STRAVA_OPENAPI_URL herunter, validiert das Swagger-Dokument und lädt dann referenzierte JSON-Dokumente herunter. Die vorhandene Kopie wird erst ersetzt, nachdem der gesamte Download- und Validierungsprozess erfolgreich abgeschlossen ist. Die gemeldete Version und die Anzahl der referenzierten Schemas werden angezeigt.

Um einen anderen Pfad zu erzwingen:

STRAVA_OPENAPI_PATH="$HOME/.config/strava-mcp/openapi.json" strava-mcp update-spec

Direkte Installation mit uvx aus Git

Die pyproject.toml deklariert die ausführbare Datei und alle Abhängigkeiten. Keine manuelle Python-Installation oder Klon erforderlich:

uvx --from git+https://github.com/Arbodgad/strava-openapi-mcp strava-mcp auth
uvx --from git+https://github.com/Arbodgad/strava-openapi-mcp strava-mcp

Um trotz des uv-Caches sofort einen neuen Commit zu verwenden:

uvx --refresh --from git+https://github.com/Arbodgad/strava-openapi-mcp strava-mcp

OpenCode-Konfiguration

Fügen Sie den Server zur OpenCode-Konfiguration hinzu:

{
  "mcp": {
    "strava": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/Arbodgad/strava-openapi-mcp",
        "strava-mcp"
      ],
      "enabled": true
    }
  }
}

Exportieren Sie die Variablen in der Umgebung, die OpenCode startet, oder verwenden Sie credentials.json, anstatt Geheimnisse in diese Datei zu committen. Führen Sie strava-mcp auth einmal für dasselbe lokale Konto aus, bevor Sie OpenCode starten.

Generierte Tools und Beispiele

Namen werden von operationId abgeleitet, in Snake Case normalisiert, und ein HTTP-Methodenpräfix wird nur hinzugefügt, wenn es zur Vermeidung von Mehrdeutigkeiten erforderlich ist. Zum Beispiel mit der aktuellen Spezifikation:

Die UpdatableActivity-Body-Parameter werden in das PUT-Tool eingebettet. Der Agent kann daher konzeptionell äquivalente Aufrufe ausführen:

put_update_activity_by_id(id=123456789, name="Long Z2 run")
put_update_activity_by_id(id=123456789, description="Easy aerobic endurance session, good sensations.")

Weitere Beispiele für Anfragen in natürlicher Sprache:

• „Liste meine letzten Laufaktivitäten auf“: Verwenden Sie get_logged_in_athlete_activities und filtern Sie dann die zurückgegebenen Ergebnisse.

• „Lies die Details von Aktivität 123“: Verwenden Sie get_activity_by_id(id=123).

• „Hole die Distanz- und Herzfrequenz-Streams für 123“: Verwenden Sie get_activity_streams(id=123, keys=["distance", "heartrate"], key_by_type=true).

• „Hole meine Statistiken“: Holen Sie den authentifizierten Athleten und verwenden Sie dann get_stats(id=...).

Die Paginierung wird vollständig durch die Parameter in der Spezifikation gesteuert (page, per_page, before, after, page_size, after_cursor usw.). Der Server startet niemals automatisch eine lange Sequenz von Seitenanfragen.

Schreibvorgänge und gefährliche Operationen

MCP-Beschreibungen enthalten This operation modifies Strava data für POST/PUT/PATCH und WARNING für DELETE. Wenn STRAVA_ALLOW_WRITE=false ist, geben Schreib-Tools einen expliziten Fehler zurück. Wenn STRAVA_ALLOW_DELETE=false ist, fehlen DELETE-Tools in list_tools und direkte Aufrufe werden abgelehnt.

HTTP-Fehler bewahren den Status, den Endpunkt, die Strava-Meldung und verfügbare Rate-Limit-Header, zum Beispiel:

HTTP 401 Unauthorized
Endpoint: PUT /activities/{id}
Message: Invalid or expired token

Eine 204-Antwort wird zum minimalen Objekt { "status": "success", "http_status": 204 }. JSON-Antworten behalten die Strava-Feldnamen bei.

CLI-Befehle

strava-mcp                       # MCP stdio server
strava-mcp auth                  # Browser OAuth + localhost callback
strava-mcp update-spec           # Validated update of the local copy
strava-mcp show-config           # Non-secret configuration
strava-mcp list-tools            # Method, endpoint, tool, and summary
strava-mcp list-tools --schemas  # Also display each inputSchema JSON

list-tools --schemas ist nützlich, um einen MCP-Client zu diagnostizieren, der ein Schema ablehnt. JSON-Schema-Schlüsselwörter wie required werden auf der relevanten Schema-Ebene angezeigt; eine Strava-Eigenschaft namens required bleibt unter properties.

Tests und Entwicklung

uv run pytest
uv run ruff check .

Tests verwenden gemockte HTTP-Transports und kontaktieren Strava nicht. Integrationstests gegen Strava werden absichtlich nicht automatisch ausgeführt.

Fehlerbehebung

• No Strava authorization found: Führen Sie strava-mcp auth mit den korrekten Anmeldedaten aus.

• OAuth scope missing: Führen Sie strava-mcp auth erneut mit dem in STRAVA_OAUTH_SCOPES angeforderten Scope aus.

• Spec update aborted: Die vorherige lokale Kopie bleibt intakt; überprüfen Sie das Netzwerk oder entfernen Sie einen benutzerdefinierten STRAVA_OPENAPI_PATH.

• Keine DELETE-Tools: Dies ist das Standardverhalten; setzen Sie STRAVA_ALLOW_DELETE=true und starten Sie neu.

• MCP-Fehler in Bezug auf stdout: Fügen Sie keine print-Aufrufe zum Servercode hinzu; Protokolle müssen mit Logging konfiguriert werden, das auf stderr schreibt.

• OAuth-Port bereits belegt: Setzen Sie STRAVA_CALLBACK_PORT auf einen verfügbaren Port und registrieren Sie gegebenenfalls die localhost-Domain in der Strava-Anwendung.

Sicherheit

Das Client-Secret, das Zugriffstoken und das Refresh-Token werden niemals in Protokollen, MCP-Beschreibungen oder Fehlermeldungen angezeigt. Lokale Anmelde- und Token-Dateien werden von Git ignoriert und mit 0600-Berechtigungen geschrieben. Committen Sie niemals .env, credentials.json oder tokens.json.