Strava Data Bridge (MCP Implementation)

This TypeScript-based server establishes an Model Context Protocol (MCP) gateway, translating complex Strava API interactions into standardized, LLM-accessible 'tools'.

Core Capabilities

• 🏃 Access athlete summaries, current profile configuration, and recent movement logs.
• 📊 Fetch granular telemetry streams from completed efforts (e.g., power output, heart rate variability, speed dynamics).
• 🗺️ Comprehensive segment interaction: discovery, viewing details, starring/unstarring favorites.
• 📍 Management and retrieval of stored navigational pathways (Routes).
• 💾 Serialization of route definitions into standard file formats (GPX or TCX) to the host system.
• 🤖 Guarantees adherence to the MCP standard for predictable, structured responses.
• 🔧 Leverages the current iteration of the Strava API (V3).

Interaction Scenarios (LLM Prompts)

Users can prompt the AI with requests such as:

Activity & Bio: * "Summarize my last five recorded athletic endeavors." * "What is my current Strava biographical summary?"

Performance Deep Dive: * "Retrieve the cadence and elevation trace for my Tuesday endurance cycle." * "Isolate the heart rate data points from my marathon training session yesterday."

Statistical Benchmarks: * "Display my lifetime cycling mileage." * "What are my top three running statistics year-to-date?"

Segment Exploration: * "Locate and list all challenging cycling segments (Category 3 or higher) within the specified coordinate box." * "Flag the 'Skyline Ridge' segment as a personal favorite."

Route Operations: * "List all my saved traversal plans." * "Generate a GPX file for the route titled 'Coastal Scenic Drive'."

Advanced Analysis Example

This illustrates chaining capabilities for sophisticated data synthesis:

Assume the persona of a performance data scientist. Analyze the most recent recorded activity. First, call the tool to acquire all available raw streams (time, power, heart rate, elevation). Next, calculate the Time in Zones (TiZ) for both power and heart rate based on my predefined zones (retrieve these first using the zones tool). Finally, synthesize a narrative report detailing training effectiveness, flagging any significant anomalies in power/HR correlation, and recommending adjustments for the next session.

⚙️ Deployment Protocol

Successful operation requires strict adherence to the initialization sequence:

1. Install server binaries and necessary packages.
2. Integrate the server configuration into the host environment (e.g., Claude configuration file).
3. Complete the OAuth 2.0 authorization dance with the Strava service.
4. Initiate a full system restart to guarantee environment variable loading.

Failure to follow this order risks configuration misalignment, particularly regarding credential ingestion.

Installation Guide (Source Method)

1. Acquire Codebase: bash git clone https://github.com/r-huijts/strava-mcp.git cd strava-mcp

2. Dependency Resolution: bash npm install

3. Compilation: bash npm run build

Host Configuration (Example for Desktop Client)

Modify your configuration file to point to the executable:

{ "mcpServers": { "strava-bridge": { "command": "node", "args": [ "/path/to/strava-mcp/dist/server.js" ] } } }

Authentication Procedure

Use the provided script to initiate the user consent flow:

bash

Ensure you have created a Strava API application first (Callback URL: localhost)

npx tsx scripts/setup-auth.ts

Environment Variables Reference

Variable Key	Necessity	Purpose
STRAVA_CLIENT_ID	Mandatory	Application API Key.
STRAVA_CLIENT_SECRET	Mandatory	Application Secret.
STRAVA_ACCESS_TOKEN	Setup Generated	Primary token for API calls.
STRAVA_REFRESH_TOKEN	Setup Generated	Used for token renewal cycles.
ROUTE_EXPORT_PATH	Optional	Destination directory for GPX/TCX files.

Token Refresh Mechanism

This server manages token lifecycles autonomously. Upon access token expiration (approx. 6 hours), the stored refresh token automatically requests a new pair from Strava. Both the active token and the persistence file (.env) are immediately updated to maintain seamless background operation. The setup script only requires execution once.

Tool Reference (Abbreviated List)

---

get-activity-streams

Function: Retrieve sequential data series from an activity, critical for detailed metric charting and path reconstruction.

Parameters: - id (Required: Number): Target activity identifier. - types (Optional: Array): Metrics to extract (e.g., watts, latlng, heartrate). Default includes core metrics. - resolution (Optional: String): Density of data points (low, medium, high). - points_per_page (Optional: Number): Controls pagination, use -1 for full unpaginated retrieval across multiple messages.

Output Focus: Structured metadata, summary statistics (max/avg HR, power), and the requested time-series data points, optimized for LLM parsing.

---

export-route-gpx / export-route-tcx

Function: Serializes route geometry and metadata into industry-standard formats and saves them to the specified filesystem location (ROUTE_EXPORT_PATH).

Parameters: - routeId (Required: Number): Identifier of the route file to generate.

Prerequisite: Environment variable ROUTE_EXPORT_PATH must point to a writable, absolute directory.

---

get-athlete-zones

Function: Retrieves the user's saved training intensity thresholds for both Heart Rate and Power.

Scope Requirement: profile:read_all is mandatory.

Output Focus: Provides a human-readable summary of zone ranges (e.g., 145-165 bpm) alongside the complete raw JSON response for depth analysis.

---

Licensing

MIT License applies. Refer to the LICENSE file for full terms.