strava-mcp

A Model Context Protocol (MCP) server that exposes your Strava data to Claude. Ask Claude about your training load, compare blocks, dig into lap splits, or analyze activity streams — all from a conversation.

Prerequisites

• Node.js 18+
• A Strava account with activities
• A Strava API application (free to create)

Strava API setup

1. Go to strava.com/settings/api and create an application.
2. Note your Client ID and Client Secret.
3. Obtain an access token and refresh token using Strava's OAuth flow. The simplest way:

• Visit https://www.strava.com/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://localhost&approval_prompt=force&scope=read,activity:read_all
• Authorize the app and copy the code from the redirect URL.
• Exchange it for tokens:

     curl -X POST https://www.strava.com/oauth/token \
       -d client_id=YOUR_CLIENT_ID \
       -d client_secret=YOUR_CLIENT_SECRET \
       -d code=YOUR_CODE \
       -d grant_type=authorization_code

• The response contains access_token, refresh_token, and expires_at.

Installation

git clone https://github.com/your-username/strava-mcp.git
cd strava-mcp
npm install

Configuration

cp .env.example .env

Edit .env with your credentials:

STRAVA_CLIENT_ID=your_client_id
STRAVA_CLIENT_SECRET=your_client_secret
STRAVA_ACCESS_TOKEN=your_access_token
STRAVA_REFRESH_TOKEN=your_refresh_token
STRAVA_TOKEN_EXPIRES_AT=1234567890   # unix timestamp from token exchange
DEBUG=false                           # set to "true" for verbose stderr logging

Tokens are held in memory only and auto-refreshed before expiry. Nothing is written back to .env.

Build & run

npm run build   # compile TypeScript → build/
npm start       # start the MCP server on stdio

For development without a build step:

npm run dev

Claude Desktop integration

Add this server to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "strava": {
      "command": "node",
      "args": ["/absolute/path/to/strava-mcp/build/index.js"],
      "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",
        "STRAVA_TOKEN_EXPIRES_AT": "0"
      }
    }
  }
}

Restart Claude Desktop after saving.

Available tools

Athlete

Activities

Analysis

Example prompts

• "How many miles did I run last month?"
• "Compare my training in January vs February."
• "Show me the lap splits for my last long run."
• "What was my average heart rate trend over the past 12 weeks?"
• "Find all my rides over 50 miles this year."

Project structure

src/
  index.ts          — MCP server entry point
  types.ts          — TypeScript interfaces and error classes
  utils.ts          — Unit conversion helpers (imperial: miles, min/mile, feet)
  logger.ts         — Debug logger (writes to stderr only)
  token-manager.ts  — In-memory OAuth token lifecycle (refresh, expiry)
  strava-client.ts  — Authenticated HTTP client with pagination
  tools/
    athlete.ts      — Athlete profile and stats tools
    activities.ts   — Activity listing and detail tools
    analysis.ts     — Training load and trend analysis tools

Notes

• Units: All display values are imperial (miles, min/mile, feet). Strava's metric API values are converted via utils.ts.
• Rate limits: Strava enforces 100 requests/15 min and 1,000/day. Tools that fetch large date ranges may hit these limits.
• Pagination: The client handles pagination automatically; pass maxItems to cap results.
• Logging: Debug output goes to stderr only, so it never corrupts the MCP stdout stream. Enable with DEBUG=true.

License

MIT