strava-openapi-mcp

MCPクライアント（特にOpenCode）とStrava REST APIの間の汎用プロキシとして動作する、ローカルPython MCPサーバーです。ツールはエンドポイントごとに実装されるのではなく、起動時にStrava公式のSwagger 2.0仕様から生成されます。

リポジトリには、仕様とその参照スキーマドキュメントのコピーが含まれています。そのため、起動時にツールリストを構築するためにインターネットアクセスは必要ありません。update-specコマンドは、検証後にユーザーコピーを更新します。

アーキテクチャ

openapi.pyはSwaggerを読み込んで検証し、ローカル参照を解決し、操作を正規化します。tools.pyは各操作を、生成されたJSON Schemaを持つMCPツールに変換します。client.pyは、Stravaのエンドポイントを個別に知ることなく、URL、パラメータ、JSONボディ、マルチパートフォームを構築します。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="..."

または、~/.config/strava-mcp/credentials.jsonに0600パーミッションで:

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

環境変数が優先されます。シークレットはログに表示されたり書き込まれたりすることはありません。

OAuth

一度実行します:

strava-mcp auth

ブラウザでStravaの認証ページが開きます。ローカルコールバックは、認証コードをaccess_token、refresh_token、expires_at、および付与されたスコープと交換します。トークンは~/.config/strava-mcp/tokens.jsonに0600パーミッションで保存されます。サーバーは期限切れのアクセストークンを自動的に更新し、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から派生し、スネークケースに正規化され、曖昧さを避けるために必要な場合にのみ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キーワードは、関連するスキーマレベルで表示されます。Stravaのプロパティrequiredは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をコミットしないでください。