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

What you can ask	What it does
"Connect my Strava account"	Links your Strava to Claude
"Check my Strava connection"	Shows connection status
"Get my Strava profile"	Shows your profile info
"What shoes do I have?"	Lists your shoes and usage distance
"What are my training zones?"	Shows HR and power zones

Activities

What you can ask	What it does
"Show my recent activities"	Lists your latest workouts
"Get all my runs from January"	Fetches activities with filters
"Analyze activity 12345"	Distance, time, elevation, pace, HR, cadence, power
"Show the laps from my last run"	Per-lap time, distance, speed, HR, cadence, power
"Get heart rate data from my ride"	Time-series streams at configurable resolution
"Show photos from my hike"	Activity photos

Stats & Progress

What you can ask	What it does
"What are my running stats?"	Recent, YTD, and all-time totals
"How far have I cycled this year?"	Activity totals by type

Routes (includes new tool)

What you can ask	What it does
"Find routes within 10 km of [location]"	NEW — nearby routes by lat/lng + max distance
"List my saved routes"	Your created routes
"Get details for my [route name]"	Route info
"Export [route] as GPX"	Download for GPS devices
"Export [route] as TCX"	Download for GPS devices

Segments

What you can ask	What it does
"Show my starred segments"	Your favorite segments
"Find segments near [location]"	Popular segments in a bounding box
"Get details on segment 12345"	Location, distance, grade, elevation, effort counts
"Star this segment"	Save to favorites
"Show my efforts on [segment]"	Your attempts with time, distance, PR/KOM rank
"Show the leaderboard for segment 12345"	Top times with optional filters

Clubs

What you can ask	What it does
"What clubs am I in?"	Lists your Strava 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

<details> <summary>Click to expand technical details</summary>

Environment Variables

Variable	Description
STRAVA_CLIENT_ID	Your Strava Application Client ID
STRAVA_CLIENT_SECRET	Your Strava Application Client Secret
STRAVA_ACCESS_TOKEN	OAuth access token
STRAVA_REFRESH_TOKEN	OAuth refresh token

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.

</details>

---

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.