strava-openapi-mcp

로컬 Python MCP 서버로, MCP 클라이언트(특히 OpenCode)와 Strava REST API 사이의 일반 프록시 역할을 합니다. 도구는 엔드포인트별로 구현되지 않습니다. 시작 시 Strava의 공식 Swagger 2.0 사양에서 생성됩니다.

저장소에는 사양과 참조된 스키마 문서의 사본이 포함되어 있습니다. 따라서 시작 시 도구 목록을 구축하기 위해 인터넷 액세스가 필요하지 않습니다. update-spec 명령은 검증 후 사용자 사본을 새로 고칩니다.

아키텍처

openapi.py는 Swagger를 로드하고 검증하며, 로컬 참조를 해결하고 작업을 정규화합니다. tools.py는 각 작업을 생성된 JSON Schema와 함께 MCP 도구로 변환합니다. client.py는 Strava 엔드포인트를 개별적으로 알지 못한 채 URL, 매개변수, JSON 본문 및 multipart 양식을 구축합니다. auth.py는 로컬 OAuth 흐름과 토큰 새로 고침을 처리합니다. server.py는 모든 것을 MCP stdio로 노출하고, cli.py는 유지 관리 명령을 제공합니다.

Strava의 현재 게시된 사양은 Swagger 2.0이며 info.version은 3.0.0입니다. 번들은 의도적으로 교체 가능한 데이터로 취급됩니다. 사양에 새 엔드포인트가 나타나면 자동으로 발견됩니다.

Related MCP server: MCP OpenAPI Connector

사전 요구 사항 및 로컬 설치

Python 3.12+ 및 uv를 권장합니다.

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

다음으로 MCP 서버를 시작합니다.

uv run strava-mcp

서버는 MCP stdin/stdout 전송에서 활성 상태를 유지합니다. 애플리케이션 로그는 stderr로 전송됩니다. stdio 전송 중에는 진단 로그를 stdout에 작성해서는 안 됩니다.

Strava 애플리케이션 만들기

1. https://www.strava.com/settings/api를 엽니다.

2. 애플리케이션을 만들고 Client ID 및 Client Secret을 기록합니다.

3. Strava는 localhost 및 127.0.0.1을 콜백 도메인으로 허용합니다. 기본 콜백은 http://127.0.0.1:8765/callback입니다.

자격 증명은 환경을 통해 제공할 수 있습니다.

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

또는 0600 권한이 있는 ~/.config/strava-mcp/credentials.json에:

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

환경 변수가 우선합니다. 비밀은 로그에 표시되거나 기록되지 않습니다.

OAuth

한 번 실행:

strava-mcp auth

브라우저가 Strava 권한 부여 페이지를 엽니다. 로컬 콜백은 인증 코드를 access_token, refresh_token, expires_at 및 부여된 범위로 교환합니다. 토큰은 0600 권한으로 ~/.config/strava-mcp/tokens.json에 저장됩니다. 서버는 만료된 액세스 토큰을 자동으로 새로 고치고 Strava가 반환할 때 회전하는 새로 고침 토큰을 유지합니다.

기본적으로 사양에 선언된 모든 범위가 요청됩니다. 하위 집합을 요청하려면:

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

공식 설명을 분석하여 명시적 범위를 유추합니다. activity:read 또는 activity:read_all을 허용하는 읽기 엔드포인트는 대안으로 표시됩니다. 조건부 범위(예: 비공개 활동의 activity:read_all)는 LLM에 표시되며 원래 Strava 오류는 계속 표시됩니다.

구성

지원되는 변수:

별칭 STRAVA_MCP_ALLOW_WRITE 및 STRAVA_MCP_ALLOW_DELETE도 허용됩니다. strava-mcp show-config는 비밀 정보가 없는 구성 보기만 표시합니다.

권장 값은 STRAVA_ALLOW_WRITE=true 및 STRAVA_ALLOW_DELETE=false입니다. POST, PUT, PATCH 메서드는 기본적으로 차단되지 않습니다. DELETE 메서드는 사양에 포함된 경우 생성되지만 STRAVA_ALLOW_DELETE=false인 동안 MCP 도구 목록에서 필터링됩니다.

첫 시작

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

사용자 사양 사본이 우선합니다. 존재하지 않으면 시작 시 아무것도 다운로드하지 않고 번들된 공식 사양을 사용합니다.

사양 업데이트

strava-mcp update-spec

이 명령은 STRAVA_OPENAPI_URL을 다운로드하고 Swagger 문서를 검증한 다음 참조된 JSON 문서를 다운로드합니다. 전체 다운로드 및 검증 프로세스가 성공한 후에만 기존 사본이 교체됩니다. 보고된 버전과 참조된 스키마 수가 표시됩니다.

다른 경로를 강제하려면:

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

Git에서 uvx로 직접 설치

pyproject.toml은 실행 파일과 모든 종속성을 선언합니다. 수동 Python 설치나 클론이 필요하지 않습니다.

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

uv 캐시에도 불구하고 새 커밋을 즉시 사용하려면:

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

OpenCode 구성

OpenCode 구성에 서버를 추가합니다.

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

OpenCode를 시작하는 환경에서 변수를 내보내거나 credentials.json을 사용하여 이 파일에 비밀을 커밋하지 마십시오. OpenCode를 시작하기 전에 동일한 로컬 계정으로 strava-mcp auth를 한 번 실행하십시오.

생성된 도구 및 예제

이름은 operationId에서 파생되며 snake case로 정규화되고, 모호성을 피하기 위해 필요한 경우에만 HTTP 메서드 접두사가 추가됩니다. 예를 들어 현재 사양에서:

UpdatableActivity 본문 매개변수는 PUT 도구로 평면화됩니다. 따라서 에이전트는 개념적으로 동일한 호출을 할 수 있습니다.

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.")

자연어 요청의 다른 예:

• "최근 달리기 활동 나열": get_logged_in_athlete_activities를 사용한 다음 반환된 결과를 필터링합니다.

• "활동 123의 세부 정보 읽기": get_activity_by_id(id=123)를 사용합니다.

• "123의 거리 및 심박수 스트림 가져오기": get_activity_streams(id=123, keys=["distance", "heartrate"], key_by_type=true)를 사용합니다.

• "내 통계 가져오기": 인증된 운동선수를 얻은 다음 get_stats(id=...)를 사용합니다.

페이지 매김은 사양의 매개변수(page, per_page, before, after, page_size, after_cursor 등)에 의해 완전히 제어됩니다. 서버는 긴 페이지 요청 시퀀스를 자동으로 시작하지 않습니다.

쓰기 및 위험한 작업

MCP 설명에는 POST/PUT/PATCH에 대해 This operation modifies Strava data가 포함되고 DELETE에 대해 WARNING이 포함됩니다. STRAVA_ALLOW_WRITE=false이면 쓰기 도구는 명시적 오류를 반환합니다. STRAVA_ALLOW_DELETE=false이면 DELETE 도구는 list_tools에 없으며 직접 호출이 거부됩니다.

HTTP 오류는 상태, 엔드포인트, Strava 메시지 및 사용 가능한 속도 제한 헤더를 유지합니다. 예:

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

204 응답은 최소 객체 { "status": "success", "http_status": 204 }가 됩니다. JSON 응답은 Strava 필드 이름을 유지합니다.

CLI 명령

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는 스키마를 거부하는 MCP 클라이언트를 진단하는 데 유용합니다. required와 같은 JSON Schema 키워드는 관련 스키마 수준에 표시됩니다. required라는 Strava 속성은 properties 아래에 유지됩니다.

테스트 및 개발

uv run pytest
uv run ruff check .

테스트는 모의 HTTP 전송을 사용하며 Strava에 연결하지 않습니다. Strava에 대한 통합 테스트는 의도적으로 자동으로 실행되지 않습니다.

문제 해결

• No Strava authorization found: 올바른 자격 증명으로 strava-mcp auth를 실행합니다.

• OAuth scope missing: STRAVA_OAUTH_SCOPES에 요청된 범위로 strava-mcp auth를 다시 실행합니다.

• Spec update aborted: 이전 로컬 사본은 그대로 유지됩니다. 네트워크를 확인하거나 사용자 지정 STRAVA_OPENAPI_PATH를 제거합니다.

• DELETE 도구 없음: 이것이 기본 동작입니다. STRAVA_ALLOW_DELETE=true로 설정하고 다시 시작합니다.

• stdout 관련 MCP 오류: 서버 코드에 print 호출을 추가하지 마십시오. 로그는 stderr에 대해 구성된 logging을 사용해야 합니다.

• OAuth 포트가 이미 사용 중: STRAVA_CALLBACK_PORT를 사용 가능한 포트로 설정하고 필요한 경우 Strava 애플리케이션에 localhost 도메인을 등록합니다.

보안

클라이언트 비밀, 액세스 토큰 및 새로 고침 토큰은 로그, MCP 설명 또는 오류 메시지에 포함되지 않습니다. 로컬 자격 증명 및 토큰 파일은 Git에서 무시되며 0600 권한으로 작성됩니다. .env, credentials.json 또는 tokens.json을 커밋하지 마십시오.