Skip to main content
Glama
strava-openapi-mcp

strava-openapi-mcp

by Arbodgad

strava-openapi-mcp

Local Python MCP server acting as a generic proxy between an MCP client—especially OpenCode—and the Strava REST API. Tools are not implemented endpoint by endpoint: they are generated at startup from Strava’s official Swagger 2.0 specification.

The repository contains a copy of the specification and its referenced schema documents. Startup therefore does not require Internet access to build the tool list. The update-spec command refreshes the user copy after validation.

Architecture

openapi.py loads and validates Swagger, resolves local references, and normalizes operations. tools.py transforms each operation into an MCP tool with a generated JSON Schema. client.py builds URLs, parameters, JSON bodies, and multipart forms without knowing Strava endpoints individually. auth.py handles the local OAuth flow and token refresh. server.py exposes everything over MCP stdio, while cli.py provides maintenance commands.

Strava’s currently published specification is Swagger 2.0, with info.version 3.0.0. The bundle is intentionally treated as replaceable data: if a new endpoint appears in the specification, it is discovered automatically.

Related MCP server: strava-mcp

Prerequisites and local installation

Python 3.12+ and uv are recommended.

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

Start the MCP server with:

uv run strava-mcp

The server remains active on the MCP stdin/stdout transport. Application logs are sent to stderr. No diagnostic log must be written to stdout during stdio transport.

Create a Strava application

  1. Open https://www.strava.com/settings/api.

  2. Create an application and note its Client ID and Client Secret.

  3. Strava accepts localhost and 127.0.0.1 as callback domains. The default callback is http://127.0.0.1:8765/callback.

Credentials can be provided through the environment:

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

Or in ~/.config/strava-mcp/credentials.json with 0600 permissions:

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

Environment variables take precedence. The secret is never displayed or written to logs.

OAuth

Run once:

strava-mcp auth

The browser opens the Strava authorization page. The local callback exchanges the authorization code for access_token, refresh_token, expires_at, and the granted scopes. Tokens are stored in ~/.config/strava-mcp/tokens.json with 0600 permissions. The server automatically refreshes expired access tokens and persists a rotating refresh token when Strava returns one.

By default, all scopes declared by the specification are requested. To request a subset:

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

Official descriptions are analyzed to infer explicit scopes. Read endpoints accepting either activity:read or activity:read_all are represented as alternatives. A conditional scope—such as activity:read_all for a private activity—is shown to the LLM, and the original Strava error remains visible.

Configuration

Supported variables:

Variable

Default

STRAVA_CLIENT_ID

none, or credentials.json

STRAVA_CLIENT_SECRET

none, or credentials.json

STRAVA_API_BASE_URL

https://www.strava.com/api/v3

STRAVA_OPENAPI_URL

https://developers.strava.com/swagger/swagger.json

STRAVA_OPENAPI_PATH

~/.config/strava-mcp/openapi.json

STRAVA_ALLOW_WRITE

true

STRAVA_ALLOW_DELETE

false

STRAVA_LOG_LEVEL

INFO

STRAVA_OAUTH_SCOPES

all declared Strava scopes

STRAVA_CALLBACK_HOST / STRAVA_CALLBACK_PORT

127.0.0.1 / 8765

The aliases STRAVA_MCP_ALLOW_WRITE and STRAVA_MCP_ALLOW_DELETE are also accepted. strava-mcp show-config displays only a non-secret configuration view.

The recommended values are STRAVA_ALLOW_WRITE=true and STRAVA_ALLOW_DELETE=false. POST, PUT, and PATCH methods are not blocked by default. DELETE methods are generated when the specification contains them, but filtered from the MCP tool list while STRAVA_ALLOW_DELETE=false.

First startup

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

The user specification copy takes precedence. If it does not exist, the bundled official specification is used without downloading anything at startup.

Update the specification

strava-mcp update-spec

The command downloads STRAVA_OPENAPI_URL, validates the Swagger document, and then downloads referenced JSON documents. The existing copy is replaced only after the entire download and validation process succeeds. The reported version and number of referenced schemas are displayed.

To force a different path:

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

Direct installation with uvx from Git

The pyproject.toml declares the executable and all dependencies. No manual Python installation or clone is required:

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

To immediately use a new commit despite the uv cache:

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

OpenCode configuration

Add the server to the OpenCode configuration:

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

Export the variables in the environment that launches OpenCode, or use credentials.json, instead of committing secrets to this file. Run strava-mcp auth once for the same local account before starting OpenCode.

Generated tools and examples

Names are derived from operationId, normalized to snake case, with an HTTP method prefix added only when necessary to avoid ambiguity. For example, with the current specification:

Endpoint

Current generated tool

GET /athlete

get_logged_in_athlete

GET /athlete/activities

get_logged_in_athlete_activities

GET /activities/{id}

get_activity_by_id

PUT /activities/{id}

put_update_activity_by_id

GET /activities/{id}/streams

get_activity_streams

GET /athletes/{id}/stats

get_stats

The UpdatableActivity body parameters are flattened into the PUT tool. The agent can therefore make conceptually equivalent calls:

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

Other examples of natural-language requests:

  • “List my latest running activities”: use get_logged_in_athlete_activities, then filter the returned results.

  • “Read the details of activity 123”: use get_activity_by_id(id=123).

  • “Get the distance and heartrate streams for 123”: use get_activity_streams(id=123, keys=["distance", "heartrate"], key_by_type=true).

  • “Get my statistics”: obtain the authenticated athlete, then use get_stats(id=...).

Pagination is fully controlled by the parameters in the specification (page, per_page, before, after, page_size, after_cursor, and so on). The server never automatically starts a long sequence of page requests.

Writes and dangerous operations

MCP descriptions include This operation modifies Strava data for POST/PUT/PATCH and WARNING for DELETE. If STRAVA_ALLOW_WRITE=false, write tools return an explicit error. If STRAVA_ALLOW_DELETE=false, DELETE tools are absent from list_tools and direct calls are rejected.

HTTP errors preserve the status, endpoint, Strava message, and available rate-limit headers, for example:

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

A 204 response becomes the minimal object { "status": "success", "http_status": 204 }. JSON responses retain Strava field names.

CLI commands

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 is useful for diagnosing an MCP client that rejects a schema. JSON Schema keywords such as required are displayed at the relevant schema level; a Strava property named required remains under properties.

Tests and development

uv run pytest
uv run ruff check .

Tests use mocked HTTP transports and do not contact Strava. Integration tests against Strava are intentionally not run automatically.

Troubleshooting

  • No Strava authorization found: run strava-mcp auth with the correct credentials.

  • OAuth scope missing: run strava-mcp auth again with the scope requested in STRAVA_OAUTH_SCOPES.

  • Spec update aborted: the previous local copy remains intact; check the network or remove a custom STRAVA_OPENAPI_PATH.

  • No DELETE tools: this is the default behavior; set STRAVA_ALLOW_DELETE=true and restart.

  • MCP error related to stdout: do not add print calls to server code; logs must use logging configured for stderr.

  • OAuth port already in use: set STRAVA_CALLBACK_PORT to an available port and, if necessary, register the localhost domain in the Strava application.

Security

The client secret, access token, and refresh token are never included in logs, MCP descriptions, or error messages. Local credential and token files are ignored by Git and written with 0600 permissions. Never commit .env, credentials.json, or tokens.json.

Available Tools

34 tools
get_activity_by_idA

Get Activity

Endpoint: GET /activities/{id}

Description: Returns the given activity that is owned by the authenticated athlete. Requires activity:read for Everyone and Followers activities. Requires activity:read_all for Only Me activities.

We strongly encourage you to display the appropriate attribution that identifies Garmin as the data source and the device name in your application. Please see example below from VeloViewer (that provides an attribution for a Garmin Forerunner device).

Attribution

Read-only operation. Scopes: one of: activity:read, activity:read_all.

Inputs: id (required), include_all_efforts.

get_activity_streamsA

Get Activity Streams

Endpoint: GET /activities/{id}/streams

Description: Returns the given activity's streams. Requires activity:read scope. Requires activity:read_all scope for Only Me activities.

Read-only operation. Scopes: one of: activity:read, activity:read_all.

Inputs: id (required), keys (required), key_by_type (required).

get_club_activities_by_idA

List Club Activities

Endpoint: GET /clubs/{id}/activities

Description: Retrieve recent activities from members of a specific club. The authenticated athlete must belong to the requested club in order to hit this endpoint. Pagination is supported. Athlete profile visibility is respected for all activities.

Read-only operation.

Inputs: id (required), page, per_page.

get_club_admins_by_idB

List Club Administrators

Endpoint: GET /clubs/{id}/admins

Description: Returns a list of the administrators of a given club.

Read-only operation.

Inputs: id (required), page, per_page.

get_club_by_idA

Get Club

Endpoint: GET /clubs/{id}

Description: Returns a given a club using its identifier.

Read-only operation.

Inputs: id (required).

get_club_members_by_idB

List Club Members

Endpoint: GET /clubs/{id}/members

Description: Returns a list of the athletes who are members of a given club.

Read-only operation.

Inputs: id (required), page, per_page.

get_comments_by_activity_idA

List Activity Comments

Endpoint: GET /activities/{id}/comments

Description: Returns the comments on the given activity. Requires activity:read for Everyone and Followers activities. Requires activity:read_all for Only Me activities.

Read-only operation. Scopes: one of: activity:read, activity:read_all.

Inputs: id (required), page, per_page, page_size, +1 more.

get_efforts_by_segment_idB

List Segment Efforts

Endpoint: GET /segment_efforts

Description: Returns a set of the authenticated athlete's segment efforts for a given segment. Requires subscription.

Read-only operation.

Inputs: segment_id (required), per_page, end_date_local, start_date_local.

get_explore_segmentsB

Explore segments

Endpoint: GET /segments/explore

Description: Returns the top 10 segments matching a specified query.

Read-only operation.

Inputs: bounds (required), max_cat, min_cat, activity_type.

get_gear_by_idA

Get Equipment

Endpoint: GET /gear/{id}

Description: Returns an equipment using its identifier.

Read-only operation.

Inputs: id (required).

get_kudoers_by_activity_idA

List Activity Kudoers

Endpoint: GET /activities/{id}/kudos

Description: Returns the athletes who kudoed an activity identified by an identifier. Requires activity:read for Everyone and Followers activities. Requires activity:read_all for Only Me activities.

Read-only operation. Scopes: one of: activity:read, activity:read_all.

Inputs: id (required), page, per_page.

get_laps_by_activity_idA

List Activity Laps

Endpoint: GET /activities/{id}/laps

Description: Returns the laps of an activity identified by an identifier. Requires activity:read for Everyone and Followers activities. Requires activity:read_all for Only Me activities.

Read-only operation. Scopes: one of: activity:read, activity:read_all.

Inputs: id (required).

get_logged_in_athleteA

Get Authenticated Athlete

Endpoint: GET /athlete

Description: Returns the currently authenticated athlete. Tokens with profile:read_all scope will receive a detailed athlete representation; all others will receive a summary representation.

Read-only operation.

Inputs: no named parameters.

get_logged_in_athlete_activitiesB

List Athlete Activities

Endpoint: GET /athlete/activities

Description: Returns the activities of an athlete for a specific identifier. Requires activity:read. Only Me activities will be filtered out unless requested by a token with activity:read_all.

Read-only operation. Scopes: one of: activity:read, activity:read_all.

Inputs: page, after, before, per_page.

get_logged_in_athlete_clubsA

List Athlete Clubs

Endpoint: GET /athlete/clubs

Description: Returns a list of the clubs whose membership includes the authenticated athlete.

Read-only operation.

Inputs: page, per_page.

get_logged_in_athlete_starred_segmentsA

List Starred Segments

Endpoint: GET /segments/starred

Description: List of the authenticated athlete's starred segments. Private segments are filtered out unless requested by a token with read_all scope.

Read-only operation.

Inputs: page, per_page.

get_logged_in_athlete_zonesB

Get Zones

Endpoint: GET /athlete/zones

Description: Returns the the authenticated athlete's heart rate and power zones. Requires profile:read_all.

Read-only operation. Scopes: required: profile:read_all.

Inputs: no named parameters.

get_route_as_gpxB

Export Route GPX

Endpoint: GET /routes/{id}/export_gpx

Description: Returns a GPX file of the route. Requires read_all scope for private routes.

Read-only operation. Scopes: required: read_all.

Inputs: id (required).

get_route_as_tcxA

Export Route TCX

Endpoint: GET /routes/{id}/export_tcx

Description: Returns a TCX file of the route. Requires read_all scope for private routes.

Read-only operation. Scopes: required: read_all.

Inputs: id (required).

get_route_by_idB

Get Route

Endpoint: GET /routes/{id}

Description: Returns a route using its identifier. Requires read_all scope for private routes.

Read-only operation. Scopes: required: read_all.

Inputs: id (required).

get_routes_by_athlete_idB

List Athlete Routes

Endpoint: GET /athletes/{id}/routes

Description: Returns a list of the routes created by the authenticated athlete. Private routes are filtered out unless requested by a token with read_all scope.

Read-only operation.

Inputs: id (required), page, per_page.

get_route_streamsB

Get Route Streams

Endpoint: GET /routes/{id}/streams

Description: Returns the given route's streams. Requires read_all scope for private routes.

Read-only operation. Scopes: required: read_all.

Inputs: id (required).

get_segment_by_idA

Get Segment

Endpoint: GET /segments/{id}

Description: Returns the specified segment. read_all scope required in order to retrieve athlete-specific segment information, or to retrieve private segments.

Read-only operation. Scopes: required: read_all.

Inputs: id (required).

get_segment_effort_by_idA

Get Segment Effort

Endpoint: GET /segment_efforts/{id}

Description: Returns a segment effort from an activity that is owned by the authenticated athlete. Requires subscription.

Read-only operation.

Inputs: id (required).

get_segment_effort_streamsA

Get Segment Effort Streams

Endpoint: GET /segment_efforts/{id}/streams

Description: Returns a set of streams for a segment effort completed by the authenticated athlete. Requires read_all scope.

Read-only operation. Scopes: required: read_all.

Inputs: id (required), keys (required), key_by_type (required).

get_segment_streamsB

Get Segment Streams

Endpoint: GET /segments/{id}/streams

Description: Returns the given segment's streams. Requires read_all scope for private segments.

Read-only operation. Scopes: required: read_all.

Inputs: id (required), keys (required), key_by_type (required).

get_statsA

Get Athlete Stats

Endpoint: GET /athletes/{id}/stats

Description: Returns the activity stats of an athlete. Only includes data from activities set to Everyone visibilty.

Read-only operation.

Inputs: id (required).

get_upload_by_idA

Get Upload

Endpoint: GET /uploads/{uploadId}

Description: Returns an upload for a given identifier. Requires activity:write scope.

Read-only operation. Scopes: required: activity:write.

Inputs: uploadId (required).

get_zones_by_activity_idB

Get Activity Zones

Endpoint: GET /activities/{id}/zones

Description: Summit Feature. Returns the zones of a given activity. Requires activity:read for Everyone and Followers activities. Requires activity:read_all for Only Me activities.

Read-only operation. Scopes: one of: activity:read, activity:read_all.

Inputs: id (required).

post_create_activityB

Create an Activity

Endpoint: POST /activities

Description: Creates a manual activity for an athlete, requires activity:write scope.

This operation modifies Strava data. Scopes: required: activity:write.

Inputs: name (required), sport_type (required), elapsed_time (required), start_date_local (required), +5 more.

post_create_uploadB

Upload Activity

Endpoint: POST /uploads

Description: Uploads a new data file to create an activity from. Requires activity:write scope.

This operation modifies Strava data. Scopes: required: activity:write.

Inputs: file, name, commute, trainer, +3 more.

put_star_segmentB

Star Segment

Endpoint: PUT /segments/{id}/starred

Description: Stars/Unstars the given segment for the authenticated athlete. Requires profile:write scope.

This operation modifies Strava data. Scopes: required: profile:write.

Inputs: id (required), starred (required).

put_update_activity_by_idB

Update Activity

Endpoint: PUT /activities/{id}

Description: Updates the given activity that is owned by the authenticated athlete. Requires activity:write. Also requires activity:read_all in order to update Only Me activities

This operation modifies Strava data. Scopes: required: activity:write; conditional: activity:read_all.

Inputs: id (required), name, type, commute, +5 more.

put_update_logged_in_athleteB

Update Athlete

Endpoint: PUT /athlete

Description: Update the currently authenticated athlete. Requires profile:write scope.

This operation modifies Strava data. Scopes: required: profile:write.

Inputs: weight (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 34 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, with clear entity-specific names (e.g., get_activity_by_id vs get_activity_streams vs get_comments_by_activity_id). Even similar operations like route exports are distinguished by format (GPX vs TCX). No overlap or ambiguity exists.

    Naming Consistency5/5

    All tools follow a uniform verb_noun pattern using HTTP method prefixes (get_, put_, post_) followed by the resource and optional identifier (e.g., put_update_activity_by_id, post_create_upload). The naming is entirely consistent across the set.

    Tool Count2/5

    With 34 tools, the server far exceeds the typical well-scoped range (3-15) and even the borderline heavy range (16-25). While the Strava API is broad, this many tools makes the surface overweight and risks overwhelming agents during tool selection.

    Completeness3/5

    The tool set covers major resources (athlete, activities, segments, routes, clubs, gear, uploads, streams) with read and some write operations, but lacks delete operations for activities and uploads, creating lifecycle gaps. Additionally, creation is missing for some resources like routes, although these may not be API-supported. Overall, notable gaps exist but the core workflows are covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server to fetch Strava activities using OAuth authentication with automatic token refresh. Allows retrieving recent activities, activities by date range, activity details, and athlete stats.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      An HTTP broker that exposes Strava data and operations (activities, routes, segments, etc.) as MCP tools, allowing users to interact with their own Strava account via natural language using per-user OAuth2 authentication.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes Strava API v3 data (activities, segments, routes, clubs, gear, streams) as tools for any MCP client. Read-only by default, with an optional --write flag to enable mutating operations.
      1
      ISC