Intervals.icu MCP Server

Claude와 ChatGPT를 Intervals.icu API와 연결하기 위한 Model Context Protocol (MCP) 서버입니다. 활동, 이벤트, 웰니스 데이터, 파워 커브, 사용자 지정 항목에 대한 인증 및 데이터 조회 도구를 제공합니다.

Model Context Protocol (MCP) 서버가 유용하다고 생각하신다면, 개발 지속을 위한 기부를 고려해 주시기 바랍니다.

요구 사항

• Python 3.12 이상

• Model Context Protocol (MCP) Python SDK

• httpx

• python-dotenv

Related MCP server: Intervals.icu MCP Server

설정

1. uv 설치 (권장)

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"

설치 후 uv의 전체 경로를 확인하세요 — 나중에 Claude Desktop을 구성할 때 필요합니다:

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

2. 저장소 클론하기

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

3. 가상 환경 만들고 활성화하기

# 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. 프로젝트 의존성 동기화

uv sync

5. 환경 변수 설정

다음 명령을 실행하여 .env.example을 복사하고 .env로 이름을 바꾸세요:

macOS/Linux:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

그런 다음 .env 파일을 편집하고 Intervals.icu athlete ID와 API 키를 설정하세요:

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

Intervals.icu API 키 가져오기

1. Intervals.icu 계정에 로그인하세요.

2. Settings > API로 이동하세요.

3. 새 API 키를 생성하세요.

Athlete ID 찾기

Athlete ID는 Intervals.icu에 로그인한 상태에서 URL에서 볼 수 있습니다. 다음과 같은 형태를 가집니다:

• https://intervals.icu/athlete/i12345/... 여기서 i12345는 사용자의 athlete ID입니다.

업데이트

이 프로젝트는 활발히 개발되고 있으며, 새 기능과 수정 사항이 정기적으로 추가됩니다. 최신 상태를 유지하려면 다음 단계를 따르세요:

1. main에서 최신 변경 사항 가져오기

⚠️ 이 명령을 실행하기 전에 커밋되지 않은 변경 사항이 없는지 확인하세요.

macOS/Linux:

git checkout main && git pull

Windows (PowerShell):

git checkout main; git pull

2. Python 의존성 업데이트

가상 환경을 활성화하고 의존성을 동기화하세요:

macOS/Linux:

source .venv/bin/activate
uv sync

Windows (PowerShell):

.venv\Scripts\activate
uv sync

문제 해결

Claude Desktop이 구성 변경으로 인해 작동하지 않으면 다음 단계를 따르세요:

1. claude_desktop_config.json에서 기존 Intervals.icu 항목을 삭제하세요.

2. intervals-mcp-server 디렉터리에서 Claude Desktop을 다시 구성하세요.

macOS/Linux:

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

Windows: Windows 구성 섹션에 설명된 대로 항목을 수동으로 다시 추가하세요.

일반적인 오류

spawn uv ENOENT — Claude Desktop이 uv 실행 파일을 찾지 못합니다. command 필드에 uv의 전체 경로를 사용하세요. 전체 경로를 확인하려면 which uv (macOS/Linux) 또는 where.exe uv (Windows)를 실행하세요.

spawn /Users/... ENOENT (Windows) — 구성 파일에 macOS/Linux 스타일 경로가 들어 있습니다. 아래 Windows 구성 섹션에 설명된 대로 백슬래시를 사용하는 올바른 Windows 경로로 교체하세요.

Windows Store 설치: 구성 변경이 적용되지 않는 경우 — 잘못된 구성 파일을 편집하고 있을 수 있습니다. Microsoft Store에서 설치한 Claude Desktop은 AppData\Roaming\Claude\가 아닌 AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json을 읽습니다.

Claude와 함께 사용하기

1. Claude Desktop 구성

이 서버를 Claude Desktop에서 사용하려면 Claude Desktop 구성에 추가해야 합니다.

macOS/Linux

1. intervals-mcp-server 디렉터리에서 다음 명령을 실행해 Claude Desktop을 구성하세요:

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

2. Claude Desktop 앱 구성 파일인 claude_desktop_config.json을 열면 다음과 같이 표시되어야 합니다:

{
  "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"
      }
    }
  }
}

여기서 /path/to/는 시스템에 있는 intervals-mcp-server 코드 폴더의 경로입니다.

Windows

mcp install 명령은 Windows에서 환경 또는 권한 문제로 실패할 수 있습니다. 대신 Claude Desktop을 수동으로 구성하세요:

1. Claude Desktop 구성 파일을 찾으세요. Claude Desktop이 Microsoft Store를 통해 설치된 경우 구성 파일은 다음 위치에 있습니다:

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

   표준 설치 프로그램으로 설치된 경우 다음 위치에 있을 수 있습니다:

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

   파일이나 폴더가 없다면 생성하세요.

2. claude_desktop_config.json에 다음 항목을 추가하고, 자리 표시자를 실제 값으로 바꾸세요:

{
  "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"
      }
    }
  }
}

• JSON의 모든 Windows 경로에는 이중 백슬래시(\\)를 사용하세요.

• uv.exe의 전체 경로를 찾으려면 PowerShell에서 where.exe uv를 실행하세요.

• 클론한 저장소의 전체 경로를 찾으려면 intervals-mcp-server 폴더 안에서 pwd를 실행하세요.

Windows Store 설치 참고: Microsoft Store에서 설치한 Claude Desktop은 AppData\Local\Packages\... 아래에 구성을 격리(sandbox)합니다. AppData\Roaming\Claude\claude_desktop_config.json을 편집해도 효과가 없으니 올바른 파일을 편집해야 합니다.

3. Claude Desktop을 다시 시작하세요.

2. Claude와 함께 MCP 서버 사용하기

서버가 실행 중이고 Claude Desktop이 구성되면 다음 도구를 사용하여 과거 및 예정된 활동, 이벤트, 운동, 웰니스 데이터에 대해 질문할 수 있습니다.

• get_activities: 활동 목록 가져오기

• get_activity_details: 특정 활동의 상세 정보 가져오기

• get_activity_intervals: 특정 활동의 상세 인터벌 데이터 가져오기

• get_activity_streams: 특정 활동의 원시 데이터 스트림 (파워, 심박수 등) 가져오기

• get_athlete_power_curves: 선택한 시간 및 기간에 대한 최고 파워 출력 커브 가져오기

• get_wellness_data: 웰니스 데이터 가져오기

• get_events: 다가오는 이벤트 (운동, 레이스 등) 가져오기

• get_event_by_id: 특정 이벤트 상세 정보 가져오기

• add_or_update_event: 이벤트(운동, 레이스, 메모 등) 만들기 또는 업데이트

• delete_event: 특정 이벤트 삭제

• delete_events_by_date_range: 날짜 범위 내 이벤트 삭제

• get_custom_items: 선수의 사용자 지정 항목(차트, 사용자 지정 필드, 구간 등) 가져오기

• get_custom_item_by_id: 특정 사용자 지정 항목 상세 정보 가져오기

• create_custom_item: 선수를 위한 새 사용자 지정 항목 만들기

• update_custom_item: 기존 사용자 지정 항목 업데이트

• delete_custom_item: 사용자 지정 항목 삭제

ChatGPT에서 사용하기

ChatGPT의 베타 MCP 커넥터는 SSE transport를 통해 이 서버와 통신할 수 있습니다.

1. 서버를 SSE 모드로 시작해서 /sse 및 /messages/ 엔드포인트를 노출하세요:

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

   시작 로그에는 전체 URL이 출력됩니다(예: http://127.0.0.1:8765/sse). ChatGPT가 공개 URL을 필요로 하므로 서버를 공개하지 않는 경우 ngrok http 8765 같은 도구를 이용해 포트를 전달하세요.

2. ChatGPT에서 Settings → Features → Custom MCP Connectors를 열고 Add를 클릭하세요. 다음을 입력하세요:

   • Name: Intervals.icu

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

   • Authentication: 터널을 보호하지 않았다면 No authentication으로 둡니다.

   여기서 동일한 ngrok http 8765 터널 URL을 재사용할 수 있습니다. 위에서 설정한 호스트/포트로 전달되는지만 확인하세요.

3. 커넥터를 저장하고 새 대화를 여세요. ChatGPT는 SSE 연결을 유지하면서 서버가 알려 /messages/ 엔드포인트로 후속 요청을 POST합니다. MCP 서버나 터널을 다시 시작하면 반드시 SSE 명령을 다시 실행하고 URL이 변경되었을 때 커넥터 URL을 업데이트하세요.

개발 및 테스트

개발 의존성을 설치하고 테스트 스위트를 실행합니다:

uv sync --all-extras
pytest -v tests

로컬에서 서버 실행

서버를 수동으로 시작하려면 (개발이나 테스트 중에 유용합니다) 다음을 실행하세요:

mcp run src/intervals_mcp_server/server.py

디버그 로깅 활성화

디버깅용 서버 로그를 수집하려면 명령을 셸(shell)로 감싸고 stderr를 파일로 리다이렉트하세요.

macOS/Linux — claude_desktop_config.json을 다음과 같이 수정하세요:

{
  "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"
      }
    }
  }
}

그런 다음 로그 파일을 tail하여 실시간 출력을 확인하세요:

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

Windows — claude_desktop_config.json을 다음과 같이 수정하세요:

{
  "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"
      }
    }
  }
}

그런 다음 PowerShell을 사용하여 로그 파일을 실시간으로 모니터링하세요:

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

라이선스

GNU General Public License v3.0

추천

Glama.ai