# Strava MCP Server — Cloudflare Workers

A personal [Model Context Protocol](https://modelcontextprotocol.io) server for Strava, hosted on Cloudflare Workers (free tier). Connect Claude to your Strava data for natural language queries about your rides, stats, and activities.

## Tools

| Tool | Description |
|------|-------------|
| `get_athlete` | Your Strava profile |
| `get_stats` | Recent, YTD, and all-time ride totals |
| `get_activities` | List recent activities with power, HR, elevation |
| `get_activity` | Detailed view of a specific activity |
| `create_activity` | Log a manual activity (strength training, etc.) |
| `update_activity` | Rename or update an existing activity |

All distances returned in **miles**, elevation in **feet**.

---

## Setup

### 1. Create a Cloudflare Account

Go to [cloudflare.com](https://www.cloudflare.com) and sign up for a free account if you don't have one.

### 2. Create a Strava API App

Follow the [Strava API Getting Started guide](https://developers.strava.com/docs/getting-started/) to create your API application. When setting up the app use these values:

- **Website:** `https://strava-mcp.YOUR_SUBDOMAIN.workers.dev`
- **Authorization Callback Domain:** `strava-mcp.YOUR_SUBDOMAIN.workers.dev` (no `https://`, no path)

Note your **Client ID** and **Client Secret** — you will need them in step 6.

Your Cloudflare subdomain is shown at [dash.cloudflare.com](https://dash.cloudflare.com) → Workers & Pages.

### 3. Fork and Connect to Cloudflare

1. Fork this repo to your GitHub account
2. In the Cloudflare dashboard, go to **Workers & Pages** → **Add** → **Continue with GitHub**
3. Authorize Cloudflare to access your GitHub account
4. Select your forked `strava-mcp` repo and click **Next**, then **Deploy**

This connects your GitHub repo to Cloudflare — every push to `main` will automatically redeploy the worker.

### 4. Install Wrangler

Wrangler is Cloudflare's CLI tool. You'll need Node.js v18+ installed first.

```bash
npm install -g wrangler
wrangler login
```

> **Important:** All `wrangler` commands must be run from inside the project directory (where `wrangler.toml` lives). If you get a "missing worker name" error, `cd` into the project folder first.

### 5. Create KV Namespace

Cloudflare KV is used to store your Strava OAuth tokens.

```bash
wrangler kv namespace create TOKENS
```

Copy the output `id` into `wrangler.toml`:

```toml
[[kv_namespaces]]
binding = "TOKENS"
id = "PASTE_YOUR_ID_HERE"
```

### 6. Set Secrets

Store all sensitive values in Cloudflare's secret store rather than in `wrangler.toml`. This keeps them out of version control and safe to commit publicly.

```bash
wrangler secret put STRAVA_CLIENT_SECRET --name strava-mcp
# Paste your Strava Client Secret when prompted

wrangler secret put STRAVA_CLIENT_ID --name strava-mcp
# Paste your Strava Client ID when prompted

wrangler secret put WORKER_URL --name strava-mcp
# Paste your full worker URL, e.g. https://strava-mcp.YOUR_SUBDOMAIN.workers.dev
```

### 7. Deploy

```bash
npm install
npm run deploy
```

### 8. Connect Strava (one-time OAuth)

Visit your worker URL in a browser to authorize Strava:

```
https://strava-mcp.YOUR_SUBDOMAIN.workers.dev/auth/login
```

Authorize the app on Strava. Tokens are stored in Cloudflare KV and auto-refreshed on every request.

You can verify everything is working by visiting the status page:

```
https://strava-mcp.YOUR_SUBDOMAIN.workers.dev/status
```

---

## Add to Claude.ai

1. Go to **Claude.ai → Settings → Integrations**
2. Add a new remote MCP server:
   ```
   https://strava-mcp.YOUR_SUBDOMAIN.workers.dev/mcp
   ```
3. That's it — Claude can now query your Strava data naturally

Example prompts:
- *"How many miles have I ridden this year?"*
- *"Show me my last 5 activities"*
- *"What were my power numbers on my ride Saturday?"*
- *"Log a 45-minute strength training session for this morning"*

---

## Local Development

Create a `.dev.vars` file (gitignored) for local secrets:

```bash
STRAVA_CLIENT_SECRET=your_secret_here
STRAVA_CLIENT_ID=your_client_id_here
WORKER_URL=http://localhost:8787
```

Then run:

```bash
npm run dev
```

---

## Architecture

```
Claude.ai → POST /mcp → Cloudflare Worker → Strava API
                              ↕
                        Cloudflare KV
                     (OAuth token storage)
```

- **Transport:** MCP Streamable HTTP (spec version 2025-03-26)
- **Auth:** Strava OAuth 2.0 with automatic token refresh
- **Storage:** Cloudflare KV (single-user, personal server)
- **Auto-deploy:** Cloudflare Workers + GitHub integration (push to `main` deploys automatically)
- **Free tier:** Cloudflare Workers free tier supports 100k requests/day