# strava-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (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](https://www.strava.com) with activities
- A Strava API application (free to create)

## Strava API setup

1. Go to [strava.com/settings/api](https://www.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:
     ```bash
     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

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

## Configuration

```bash
cp .env.example .env
```

Edit `.env` with your credentials:

```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=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

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

For development without a build step:

```bash
npm run dev
```

## Claude Desktop integration

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

```json
{
  "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

| Tool | Description |
|------|-------------|
| `get_athlete` | Profile: name, location, weight, FTP, membership type |
| `get_athlete_stats` | Activity totals (recent / YTD / all-time) for rides, runs, swims |
| `get_athlete_zones` | Heart rate and power training zones from your Strava settings |

### Activities

| Tool | Description |
|------|-------------|
| `list_activities` | Recent activities with optional date range and count cap |
| `get_activity` | Full detail for a single activity by ID |
| `get_activity_laps` | Lap splits (pace, HR, power) for a single activity |
| `get_activity_zones` | HR and power zone distributions for a single activity *(Strava Summit required)* |
| `search_activities` | Filter recent activities by name keyword and/or sport type |

### Analysis

| Tool | Description |
|------|-------------|
| `analyze_training_load` | Volume, time, elevation, and weekly breakdown over a date range |
| `compare_training_blocks` | Side-by-side comparison of two training periods with deltas |
| `get_training_timeseries` | Week-by-week or day-by-day volume trend over a date range |
| `get_activity_streams` | Raw sensor data (HR, pace, power, altitude, cadence) with summary stats |

## 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