Strava MCP Server

Talk to your Strava data using AI.

Connect Claude to your Strava account and ask questions in plain English: "How far did I run this month?", "Analyze my last ride", or "Show me my fastest segments."

This is a fork of r-huijts/strava-mcp. See What's different in this fork for the full list of changes.

What's Different in This Fork

🔑 Auto-Authentication — No More "Connect my Strava"

The original requires you to run connect-strava every time your token expires. This fork handles it automatically:

• Proactive refresh: If your token expires within 5 minutes, it's refreshed before the API call.

• Reactive refresh: Any 401 response triggers a silent token refresh and retries the request — you never see an auth error mid-session.

• Persistent tokens: After a refresh, the new token is saved to ~/.config/strava-mcp/config.json. On the next server restart, the saved (valid) token is preferred over the potentially-stale token in your env/config file. You stay logged in.

Set your credentials once in claude_desktop_config.json with STRAVA_CLIENT_ID, STRAVA_CLIENT_SECRET, STRAVA_ACCESS_TOKEN, and STRAVA_REFRESH_TOKEN — the server handles the rest.

🗺️ New Tool: find-nearby-routes

Find your saved Strava routes that start near a location, sorted by distance:

"Show me my routes within 15 km of Istanbul" "Find cycling routes near 48.8566, 2.3522"

Parameters: latitude, longitude, maxDistanceKm (default: 10 km), optional activityType (ride/run).

Uses the Haversine formula to calculate great-circle distances. Automatically paginates through all your saved routes.

🐛 Bug Fixes

• z.coerce.number() for all ID parameters: Claude serializes tool parameters as strings. The original used z.number() which rejected them with Expected number, received string. All ID params (activityId, segmentId, effortId, athleteId) now use z.coerce.number().

• Consistent activityId naming: getActivityLaps and getActivityStreams previously used id in their schemas, causing Required, received undefined errors when Claude passed activityId. Renamed to match.

📝 Improved Tool Descriptions & Error Messages

• All tool descriptions use active voice and describe what fields are returned, so Claude chooses the right tool more reliably.

• Removed "Obtain this ID first by calling..." meta-hints that caused unnecessary chained calls.

• All 26 tools return consistent, user-friendly error messages.

What Can You Do With This?

Once connected, just talk to Claude like you're talking to a friend who has access to all your Strava data:

🏃 Track Your Progress

"How many kilometers did I run this month?"

"Compare my running stats from January to December"

"What's my longest ride ever?"

📊 Analyze Your Workouts

"Break down my last cycling workout - show me power, heart rate, and cadence"

"How did my heart rate zones look during yesterday's run?"

"What was my average pace for each lap in my interval training?"

🗺️ Explore Routes & Segments

"Find my saved routes within 20 km of my location"

"What are the most popular cycling segments near Central Park?"

"Export my Sunday morning route as a GPX file"

🏆 Get Coaching Insights

"Analyze my training load this week"

"How does my current fitness compare to last month?"

"Give me a summary of my cycling performance this year"

Quick Start (3 Steps)

Step 1: Add to Claude Desktop

Open your Claude Desktop configuration file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this to the file:

{
  "mcpServers": {
    "strava": {
      "command": "npx",
      "args": ["-y", "@stugal/strava-mcp-server"],
      "env": {
        "STRAVA_CLIENT_ID": "your_client_id",
        "STRAVA_CLIENT_SECRET": "your_client_secret",
        "STRAVA_ACCESS_TOKEN": "your_access_token",
        "STRAVA_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Setting the env vars here means you never need to run connect-strava — tokens are refreshed automatically.

Step 1 (alternative): Add to Claude Code

claude mcp add --transport stdio strava -- npx @stugal/strava-mcp-server

Step 2: Restart Claude Desktop

Close and reopen Claude Desktop to load the new configuration.

Step 3: Start Talking

That's it! Ask Claude about your Strava data directly. If you provided credentials in Step 1, you're already authenticated.

If you didn't set env vars, say:

"Connect my Strava account"

Connecting Your Strava Account

Getting Your Strava API Credentials

You need to create a free Strava API application (one-time setup):

1. Go to strava.com/settings/api

2. Click "Create an App" (or view your existing app)

3. Fill in the form:

   • Application Name: Anything you want (e.g., "My Claude Assistant")

   • Category: Choose any

   • Website: Can be anything (e.g., http://localhost)

   • Authorization Callback Domain: Must be localhost

4. Copy your Client ID and Client Secret

Getting Your Access & Refresh Tokens

Run the initial OAuth flow once to get your tokens:

1. Add only STRAVA_CLIENT_ID and STRAVA_CLIENT_SECRET to your config

2. Say "Connect my Strava account" — a browser window opens

3. Authorize the app on Strava

4. Your tokens are saved to ~/.config/strava-mcp/config.json

5. Copy them from there into your claude_desktop_config.json env block

After this one-time setup, token refresh is fully automatic.

Managing Your Connection

• Check status: "Am I connected to Strava?"

• Force reconnect: "Connect my Strava account"

• Disconnect: "Disconnect my Strava account"

Installation Options

Option A: Just Use It (Recommended)

No installation needed! The npx command automatically downloads and runs the latest version.

Option B: Install Globally

npm install -g @stugal/strava-mcp-server

Option C: Build from Source

git clone https://github.com/samitugal/strava-mcp.git
cd strava-mcp
npm install
npm run build

Then point Claude to your local build:

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

Available Tools

Account & Profile

Activities

Stats & Progress

Routes (includes new tool)

Segments

Clubs

Troubleshooting

Token errors after restart

This fork saves refreshed tokens to ~/.config/strava-mcp/config.json and prefers them over env var tokens on restart. If you're still seeing auth errors, delete the config file and re-authenticate:

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

Then say "Connect my Strava account".

First npx run is slow

npx downloads the package on first run (~30 seconds). Subsequent runs use the cache and start immediately.

Claude doesn't see the Strava tools

• Make sure your claude_desktop_config.json is valid JSON (no trailing commas!)

• Restart Claude Desktop after config changes

• Verify with: npx -y @stugal/strava-mcp-server — you should see the server start message

"Scope not found" or similar npm errors

Make sure you're using @stugal/strava-mcp-server, not the original @r-huijts/strava-mcp-server.

For Developers

Environment Variables

Token Refresh Flow

1. getValidToken() is called at the start of every tool execution

2. If expiresAt is known and within 5 minutes, token is proactively refreshed

3. If no token exists but refresh token does, refresh is attempted automatically

4. Any 401 response from the API triggers handleApiError() → silent refresh → retry

5. Refreshed tokens are saved to both process.env and ~/.config/strava-mcp/config.json

6. On next server start, loadConfig() prefers the saved file token if it's still valid

Config Priority

1. ~/.config/strava-mcp/config.json — if token is valid (not expired) ← new behavior

2. Environment variables

3. Local .env file

Building & Testing

npm install
npm run build
npm test

Activity Streams Optimization

The get-activity-streams tool uses a compact format by default, reducing payload size by ~70-80%:

• Compact format (default): Raw arrays with metadata, ideal for LLM processing

• Verbose format: Human-readable objects with formatted values

• Smart chunking: Large activities split into ~50KB chunks

• Intelligent downsampling: Reduces large datasets while preserving peaks and valleys

API Reference

The server implements the Model Context Protocol (MCP) and exposes 26 tools for Strava API v3. See src/tools/ for implementation details.

Contributing

Contributions welcome! Please submit a Pull Request to samitugal/strava-mcp.

Credits

This project is a fork of r-huijts/strava-mcp by Rick Huijts. The original project provides the solid MCP foundation and Strava API integration that this fork builds on.

License

MIT License - see LICENSE file for details.

Questions or issues? Open an issue on GitHub.