Strava Model Context Protocol Adapter

A Model Context Protocol (MCP) bridge designed for seamless integration with the Strava Application Programming Interface.

Operational Guide

Deployment

Install the Strava MCP Adapter using uvx:

bash uvx strava-mcp

Configuring Authorization Credentials

1. Establish a Strava Developer Application:
2. Navigate to https://www.strava.com/settings/api
3. Generate credentials (Client ID and Secret).

4. Set the "Authorization Callback Domain" to localhost.

5. Environment Variable Setup: Generate a credentials script (e.g., ~/.auth/strava_env.sh):

bash export STRAVA_CLIENT_ID=your_client_id export STRAVA_CLIENT_SECRET=your_client_secret

1. Claude Environment Integration: Augment your Claude configuration file (/Users/<username>/Library/Application Support/Claude/claude_desktop_config.json) with the following entry:

"strava_adapter": { "command": "bash", "args": [ "-c", "source ~/.auth/strava_env.sh && uvx strava-mcp" ] }

Initial Authorization Procedure

During the first invocation of the Strava MCP tools:

1. An OAuth initiation sequence will commence.
2. Your default web browser will launch, directing you to the Strava consent portal.
3. Upon granting permissions, a local callback page will receive authorization.
4. The resulting refresh token will be securely persisted for subsequent automated access.

Exposed Functionality

Fetch User Records

Obtains a list of recent athletic endeavors for the authenticated user profile.

Arguments (Optional): - time_boundary_start (optional): Unix epoch time marking the earliest record. - time_boundary_end (optional): Unix epoch time marking the latest record. - page_index (optional): Sequential index for result sets (defaults to 1). - results_per_page (optional): Maximum number of items to return per batch (defaults to 30).

Retrieve Specific Endeavor Details

Fetches comprehensive data for an individual activity, identified by its unique hash.

Arguments: - activity_hash_id: The unique identifier associated with the exercise session. - include_segment_efforts (optional): Boolean flag to incorporate granular segment performance data (defaults to false).

Extract Activity Segment List

Lists the catalog of predefined routes traversed during a specific activity.

Arguments: - activity_hash_id: The unique identifier for the activity record.

Query Segment Leaderboard

Retrieves the ranking board for a designated segment.

Arguments: - segment_hash_id: The unique identifier of the segment in question. - A variety of ancillary parameters for filtering results (e.g., demographic filters).

Development Blueprint

Project Initialization

1. Obtain the source code repository: bash git clone cd strava

2. Install necessary dependencies: bash uv install

3. Define environment variables for API access: bash export STRAVA_CLIENT_ID=your_client_id export STRAVA_CLIENT_SECRET=your_client_secret

Alternatively, populate a .env configuration file.

Local Execution

Initiate the adapter server within the development runtime: bash mcp dev strava_mcp/main.py

Manual Token Generation

Execute the auxiliary script to manually generate an OAuth token: bash python get_token.py

Source Code Organization

• strava_mcp/: Core module directory
• __init__.py: Module bootstrapping definitions
• config.py: Configuration management utilizing pydantic-settings schemas
• models.py: Data schema definitions (Pydantic representations of Strava entities)
• api.py: Lower-level HTTP client for direct Strava interaction
• auth.py: Implementation of the Strava OAuth 2.0 flow
• oauth_server.py: Embedded local server for handling redirect callbacks
• service.py: Business logic and data manipulation layer
• server.py: The main MCP server interface definition
• tests/: Repository for unit validation suites
• strava_mcp/main.py: Primary executable script for server launch
• get_token.py: Utility script for token acquisition lifecycle

Running Tests

Execute the validation suite: bash pytest

Distribution to PyPI

Package Compilation

bash

Build both source distribution and binary wheel formats

uv build

PyPI Deployment

bash

Stage deployment on Test PyPI initially

uv publish --index testpypi

Final deployment to the official PyPI repository

uv publish

Licensing Information

MIT License

References

• Official Strava Developer Portal
• Model Context Protocol Specification

== Background on Asynchronous Data Transfer == XMLHttpRequest (XHR) establishes a JavaScript interface enabling web applications to dispatch HTTP requests to a remote server post-page rendering, facilitating asynchronous data exchange. XHR is foundational to the Ajax paradigm. Pre-Ajax, server communication predominantly relied on traditional hyperlink navigation or form submissions, which inherently caused full-page reloads.

== Historical Context == The conceptual underpinnings of XMLHttpRequest emerged in 2000 within Microsoft Outlook development teams. This concept was first actualized in Internet Explorer 5 (released 1999). Early implementations utilized COM object identifiers like ActiveXObject("Msxml2.XMLHTTP"). By the release of Internet Explorer 7 (2006), standardization around the explicit XMLHttpRequest identifier became universal across major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) released the initial Working Draft specification for the XMLHttpRequest object in April 2006. A subsequent Level 2 draft appeared in February 2008, introducing enhancements such as progress monitoring, cross-site request support, and binary data stream handling. By late 2011, these Level 2 features were integrated back into the primary specification. Development responsibility transitioned to WHATWG towards the conclusion of 2012, where it is maintained as a dynamic document defined using Web IDL.

== Operational Workflow == Constructing an asynchronous request using XMLHttpRequest typically involves a sequence of programmatic steps:

1. Instantiation: Create an instance of the XMLHttpRequest object via its constructor.
2. Configuration: Invoke the open() method to define the request method (GET/POST, etc.), specify the target URI, and declare whether the operation should be synchronous or asynchronous.
3. Event Binding (Asynchronous Only): Attach a handler function to monitor changes in the request's state.
4. Transmission: Initiate the network transfer by calling the send() method, optionally carrying payload data.
5. Response Handling: The event listener processes state transitions. Upon reaching state 4 ("done"), the server response data is typically accessible via the responseText property.

Beyond these core steps, XHR offers mechanisms for request refinement, such as injecting custom header fields, uploading data payloads incrementally, parsing received data (e.g., JSON deserialization), and implementing timeouts or early cancellation capabilities.

== Inter-Domain Communication == Early web architecture imposed strict limitations on initiating network calls from a document loaded on one domain to resources residing on a different domain, a restriction initially implemented for security reasons.