ondreian/strava-mcp

Strava MCP Server

A Model Context Protocol (MCP) server for the Strava API. Provides Claude with tools to fetch and analyze your Strava activities, athlete stats, and gear.

Features

• Automatic OAuth flow - Opens browser for authorization on first run
• Token management - Auto-refreshes access tokens, stores securely in XDG directories
• Smart caching - Caches athlete profile and gear data to reduce API calls
• Comprehensive tools - Access activities, streams, photos, stats, and gear

Setup

Prerequisites

• Python 3.13+
• Strava API credentials (client ID and secret)
• uv package manager

Get Strava API Credentials

1. Go to https://www.strava.com/settings/api
2. Create an application
3. Note your Client ID and Client Secret
4. Set Authorization Callback Domain to localhost

Install

cd strava-mcp
uv sync

Configure Credentials

Create ~/.config/strava/credentials.sh:

mkdir -p ~/.config/strava
cat > ~/.config/strava/credentials.sh << 'EOF'
export STRAVA_CLIENT_ID=YOUR_CLIENT_ID
export STRAVA_CLIENT_SECRET=YOUR_CLIENT_SECRET
EOF

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual credentials.

Usage

Standalone Testing

source ~/.config/strava/credentials.sh
uv run python -m strava_mcp

On first run, this will:

1. Open your browser to Strava's authorization page
2. Wait for you to approve access
3. Store tokens in ~/.local/share/strava-mcp/tokens.json
4. Start the MCP server

MCP Configuration

In your Claude Code project, create or update .mcp.json:

{
  "strava": {
    "command": "bash",
    "args": [
      "-c",
      "source ~/.config/strava/credentials.sh && cd /absolute/path/to/strava-mcp && uv run python -m strava_mcp"
    ]
  }
}

Update /absolute/path/to/strava-mcp to the actual path.

Available Tools

get_recent_activities

Fetch recent activities with pagination.

• Args: per_page (default 30), page (default 1)
• Returns: List of activity summaries

get_activity

Get detailed information for a single activity.

• Args: activity_id
• Returns: Full activity details including segments and splits

get_activity_streams

Get time-series data (HR, power, cadence, temperature, etc.)

• Args: activity_id, keys (comma-separated stream types)
• Returns: Stream data arrays

get_athlete

Get your athlete profile (cached for 1 day).

• Args: refresh (bool, force cache refresh)
• Returns: Athlete profile with ID, name, weight, etc.

get_athlete_stats

Get yearly and all-time statistics.

• Returns: Total distance, elevation, time for recent/ytd/all-time

get_activity_photos

Get photos attached to an activity.

• Args: activity_id, size (pixels, default 600)
• Returns: List of photo data

get_gear

Get your bikes and shoes (cached for 1 week).

• Args: refresh (bool, force cache refresh)
• Returns: Dict with 'bikes' and 'shoes' lists

reauthorize

Force a new OAuth flow (useful if scopes change).

• Returns: Success message

Data Storage

All data is stored in XDG-compliant directories:

• Tokens: ~/.local/share/strava-mcp/tokens.json
• Athlete cache: ~/.local/share/strava-mcp/athlete.json
• Gear cache: ~/.local/share/strava-mcp/gear.json

Rate Limits

Strava API limits:

• 200 requests per 15 minutes
• 2000 requests per day

This server caches data where appropriate to minimize API calls.

Troubleshooting

"Authorization failed"

• Check that your client ID and secret are correct
• Ensure callback domain is set to localhost in Strava API settings

"Token refresh failed"

• Run reauthorize tool to trigger a fresh OAuth flow
• Or manually delete ~/.local/share/strava-mcp/tokens.json

Rate limit errors

• Wait for the time specified in error message
• Consider using cached tools (get_athlete, get_gear) instead of fresh requests

Development

Run tests:

uv run pytest

Format code:

uv run ruff format .

License

MIT