Intervals.icu MCP Server

Model Context Protocol (MCP)-Server zum Verbinden von Claude und ChatGPT mit der Intervals.icu API. Er bietet Werkzeuge für Authentifizierung und Datenabruf für Aktivitäten, Ereignisse, Wellness-Daten, Leistungskurven und benutzerdefinierte Elemente.

Wenn Sie den Model Context Protocol (MCP)-Server nützlich, unterstützen Sie bitte die weitere Entwicklung mit einer Spende.

Voraussetzungen

• Python 3.12 oder höher

• Model Context Protocol (MCP) Python SDK

• httpx

• python-dotenv

Related MCP server: Intervals.icu MCP Server

Einrichtung

1. uv installieren (empfohlen)

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Ermitteln Sie nach der Installation den vollständigen Pfad zu uv – Sie benötigen ihn später bei der Konfiguration von Claude Desktop:

where.exe uv
# Example output: C:\Users\<USERNAME>\.local\bin\uv.exe

2. Dieses Repository klonen

git clone https://github.com/mvilanova/intervals-mcp-server.git
cd intervals-mcp-server

3. Virtuelle Umgebung erstellen und aktiveren

# Create virtual environment with Python 3.12
uv venv --python 3.12

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

4. Projektabhängigkeiten synchronisieren

uv sync

5. Umgebungsvariablen einrichten

Erstellen Sie eine Kopie von .env.example und nennen Sie die Kopie .env, indem Sie den folgenden Befehl ausführen:

macOS/Linux:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

Bearbeiten Sie anschließend die Datei .env und setzen Sie Ihre Intervals.icu Athleten-ID sowie Ihren API-Schlüssel ein:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

So erhalten Sie Ihren Intervals.icu-API-Schlüssel

1. Melden Sie sich bei Ihrem Intervals.icu-Konto an.

2. Gehen Sie zu Einstellungen > API.

3. Erzeugen Sie einen neuen API-Schlüssel.

So finden Sie Ihre Athleten-ID

Ihre Athleten-ID ist üblich in der URL sichtbar, wenn Sie bei Intervals.icu angemeldet sind. Sie sieht wie folgt aus:

• https://intervals.icu/athlete/i12345/... – hierbei ist i12345 Ihre Athleten-ID

Aktualisierung

Dieses Projekt wird aktiv weiterentwickelt. Regelmäßig kommen neue Features und Fehlerbehebungen hinzu. Bleiben Sie mit folgenden Schritten auf dem aktuellen Stand:

1. Die neuesten Änderungen von main abrufen

⚠️ Stellen Sie sicher, dass Sie keine nicht committeten Änderungen haben, bevor Sie diesen Befehl ausführen.

macOS/Linux:

git checkout main && git pull

Windows (PowerShell):

git checkout main; git pull

2. Python-Abhängigkeiten aktualisieren

Aktivieren Sie Ihre virtuelle Umgebung und synchronisieren Sie die Abhängigkeiten:

macOS/Linux:

source .venv/bin/activate
uv sync

Windows (PowerShell):

.venv\Scripts\activate
uv sync

Fehlerbehebung

Falls Claude Desktop wegen Konfigurationsänderungen fehlschlägt, gehen Sie wie folgt vor:

1. Löschen Sie den vorhandenen Eintrag Intervals.icu in claude_desktop_config.json.

2. Konfigurieren Sie Claude Desktop erneut vom Verzeichnis intervals-mcp-server aus.

macOS/Linux:

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env

Windows: Fügen Sie den Eintrag manuell hinzu, wie im Abschnitt Windows-Konfiguration beschrieben.

Häufige Fehler

spawn uv ENOENT – Claude Desktop kann die ausführbare Datei uv nicht finden. Verwenden Sie im Feld command den vollständigen Pfad zu uv. Führen Sie which uv (macOS/Linux) oder where.exe uv (Windows) aus, um den Pfad zu erhalten.

spawn /Users/... ENOENT auf Windows – Die Konfigurationsdatei enthält einen Pfad im macOS/Linux-Stil. Ersetzen Sie ihn durch den korrekten Windows-Pfad mit Backslashes, wie unten im Abschnitt Windows-Konfiguration beschrieben.

Windows-Store-Installation: Konfigurationsänderungen werden nicht übernommen – Möglicherweise bearbeiten Sie die falsche Konfigurationsdatei. Claude Desktop aus dem Microsoft Store liest aus AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json, nicht aus AppData\Roaming\Claude\.

Verwendung mit Claude

1. Claude Desktop konfigurieren

macOS/Linux

1. Führen Sie den folgenden Befehl im Verzeichnis intervals-mcp-server aus, um Claude Desktop zu konfigurieren:

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env

2. Wenn Sie die Konfigurationsdatei von Claude Desktop claude_desktop_config.json öffnen, sollte sie in etwa so aussehen:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "/Users/<USERNAME>/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/intervals-mcp-server",
        "mcp",
        "run",
        "/path/to/intervals-mcp-server/src/intervals_mcp_server/server.py"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

wobei /path/to/ den Pfad zum Codeordner intervals-mcp-server auf Ihrem System angibt.

Windows

Der Befehl mcp install kann auf Windows aufgrund von Umgebungs- oder Berechtigungsprobleme fehlschlagen. Konfigurieren Sie Claude Desktop stattdessen manuell:

1. Finden Sie die Claude-Desktop-Konfigurationsdatei. Wenn Claude Desktop aus dem Microsoft Store installiert wurde, befindet sich die Konfiguration unter:

   C:\Users\<USERNAME>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

Falls es mit dem Standardinstallationsprogramm installiert wurde, liegt es möglicherweise unter:

C:\Users\<USERNAME>\AppData\Roaming\Claude\claude_desktop_config.json

Wenn die Datei oder der Ordner nicht vorhanden ist, erstellen Sie es.

2. Fügen Sie den folgenden Eintrag in claude_desktop_config.json ein und ersetzen Sie die Platzhalter mit Ihren tatsächlichen Werten:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "C:\\path\\to\\intervals-mcp-server",
        "mcp",
        "run",
        "C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

• Verwenden Sie in JSON doppelte Backslashes (\\) für alle Windows-Pfade.

• Um den vollständigen Pfad zu uv.exe zu erhalten, führen Sie where.exe uv in PowerShell aus.

• Um den vollständigen Pfad zum Klon zu erhalten, führen Sie pwd im Ordner intervals-mcp-server aus.

Hinweis für Windows-Store-Installationen: Claude Desktop aus dem Microsoft Store kapselt die Konfiguration unter AppData\Local\Packages\.... Eine Änderung an AppData\Roaming\Claude\claude_desktop_config.json hat keine Wirkung. Stellen Sie sicher, dass Sie die richtige Datei bearbeiten.

3. Starten Sie Claude Desktop neu.

2. Den MCP-Server mit Claude verwenden

Wenn der Server läuft und Claude Desktop konfiguriert ist, können Sie die folgenden Werkzeuge verwenden, um Fragen zu vergangenen und zukünftigen Aktivitäten, Ereignissen und Wellnessdaten zu stellen.

• get_activities: Ruft eine Liste von Aktivitäten ab

• get_activity_details: Ruft detaillierte Informationen zu einer bestimmten Aktivität ab

• get_activity_intervals: Ruft detaillierte Intervalldaten für eine bestimmte Aktivität ab

• get_activity_streams: Ruft die Rohdatenströme (Leistung, Herzfrequenz usw.) für eine bestimmte Aktivität ab

• get_athlete_power_curves: Ruft die besten Leistungskurven für ausgewählte Dauern und Zeiträume ab

• get_wellness_data: Ruft Wellnessdaten ab

• get_events: Ruft bevorstehende Ereignisse ab (Übungseinheiten, Rennen usw.)

• get_event_by_id: Ruft detaillierte Informationen zu einem bestimmten Ereignis ab

• add_or_update_event: Erstellt oder aktualisiert ein Ereignis (Training, Rennen, Notiz usw.)

• delete_event: Löscht ein bestimmtes Ereignis

• delete_events_by_date_range: Löscht Ereignisse innerhalb eines Datumsbereichs

• get_custom_items: Ruft benutzerdefinierte Elemente (Diagramme, benutzerdefinierte Felder, Zonen usw.) für einen Athleten ab

• get_custom_item_by_id: Ruft detaillierte Informationen zu einem bestimmten benutzerdefinierten Element ab

• create_custom_item: Erstellt ein neues benutzerdefiniertes Element für einen Athleten

• update_custom_item: Aktualisiert ein vorhandenes benutzerdefiniertes Element

• delete_custom_item: Löscht ein benutzerdefiniertes Element

Verwendung mit ChatGPT

Die Beta-MCP-Connectors von ChatGPT können ebenfalls über den SSE-Transport mit diesem Server sprechen.

1. Starten Sie den Server im SSE-Modus, damit er die/ sse- und /messages/-Endpunkte exponiert:

export FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8765 MCP_TRANSPORT=sse FASTMCP_LOG_LEVEL=INFO
python src/intervals_mcp_server/server.py

Das Startprotokoll gibt die vollständigen URLs aus (z. B. http://127.0.0.1:8765/sse). ChatGPT benötigt die öffentlich erreichbare URL. Leiten Sie den Port daher mit einem Werkzeug wie ngrok http 8765 weiter, wenn Sie den Server nicht direkt verfügbar machen.

2. Öffnen Sie in ChatGPT Einstellungen → Features → Custom MCP Connectors und klicken Hinzufügen. Füllen Sie Folgendes aus:

• Name: Intervals.icu

• MCP Server URL: https://<your-public-host>/sse

• Authentication: Auf Keine Authentifizierung belassen, falls Sie Ihren Tunnel nicht geschützt haben.

Sie können dieselbe ngrok http 8765-Tunnel-URL verwenden; stellen Sie nur sicher, dass dieses zu dem zuvor eingerichteten Host/Port weiterleitet.

3. Speichern Sie den Connector und öffnen Sie einen neuen Chat. ChatGPT hält die SSE-Verbindung offen und sendet (POST) nachfolgende Anfragen an den /messages/-Endpunkt, den der Server angemeldnet hat. Falls Sie den MCP-Server oder den Tunnel neu starten, führen Sie den SSE-Befehl erneut aus und aktualisieren Sie bei der Änderung die Connector-URL.

Entwicklung und Tests

Installieren Sie die Entwicklung ohne test:

uv sync --all-extras
pytest -v tests

Den Server lokal ausführen

Um den Server manuell zu starten (nützlich bei Entwicklung und Tests), führen Sie aus:

mcp run src/intervals_mcp_server/server.py

Debug-Logging aktivieren

Um Server-Logs für das Debuggen zu erfassen, umgeben Sie den Befehl in einer Shell und leiten Sie stderr in eine Datei um.

macOS/Linux – Ändern Sie claude_desktop_config.json wie folgt:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "/Users/<USERNAME>/.local/bin/uv run --with 'mcp[cli]' --with-editable /path/to/intervals-mcp-server mcp run /path/to/intervals-mcp-server/src/intervals_mcp_server/server.py 2>> /path/to/intervals-mcp-server/mcp-server.log"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Anschließend verfolgen Sie die Logdatei in Echtzeit:

tail -f /path/to/intervals-mcp-server/mcp-server.log

Windows – Ändern Sie claude_desktop_config.json wie folgt:

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "powershell",
      "args": [
        "-Command",
        "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe run --with 'mcp[cli]' --with-editable C:\\path\\to\\intervals-mcp-server mcp run C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py 2>> C:\\path\\to\\intervals-mcp-server\\mcp-server.log"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Überwachen Sie die Logdatei in Echtzeit in PowerShell:

Get-Content C:\path\to\intervals-mcp-server\mcp-server.log -Wait

Lizenz

Die GNU General Public License v3.0

Vorgestellt

Glama.ai