Strava MCP

A Model Context Protocol (MCP) server that supplements the official Strava MCP connector. It adds write access, segments, routes, photos, derived analysis, and interactive visualizations that the official connector does not provide.

Features

• Write and update activities (title, description, sport type, gear, flags)
• Create manual activities for sessions with no device recording (strength, yoga, treadmill)
• Explore, view, star, and manage segments
• Fetch per-activity photos, zone breakdowns, and running summaries
• List and view details of saved routes
• Export routes (GPX/TCX) and activity tracks (GPX built from streams)
• Derived analysis Strava does not expose: interval detection, climb/descent breakdown, aerobic decoupling, training load, fitness/fatigue/form (CTL/ATL/TSB), and a solved taper to a target race-day form
• AI-friendly JSON responses via MCP
• Nine interactive visualizations rendered in MCP-compatible hosts — activity chart, cadence trends, route map, activity segments, training load, compare activities, activity zones, segment progress, and fitness trend
• Guided prompts for weekly reviews, annotating a run, and segment hunting
• Automatic token refresh
• Streamable HTTP transport for remote deployment

Browse the UI components in the live Storybook.

Quick Start (Docker)

1. Create a Strava API Application

1. Go to strava.com/settings/api
2. Create a new application:
   • Enter your application details (name, website, description)
   • Set "Authorization Callback Domain" to your public URL hostname (e.g., strava-mcp.example.com)
   • Note your Client ID and Client Secret

2. Configure Environment

cp .env.example .env

Edit .env with your values:

STRAVA_CLIENT_ID=your_client_id
STRAVA_CLIENT_SECRET=your_client_secret
PUBLIC_URL=https://your-public-url.example.com

3. Start the Server

docker compose up -d

Prefer a prebuilt image? Instead of building locally you can pull the published image:

docker pull ghcr.io/ljcl/strava-mcp:latest

Point your docker-compose.yml image: at ghcr.io/ljcl/strava-mcp:latest (and drop the build: block) to run it without a local build.

Every release is also published to the MCP registry as io.github.ljcl/strava-mcp, so a client that reads the registry can find the same OCI package by name. The registry entry only points at the image — you still supply the Strava credentials from Environment Variables and authorize at /auth/start.

Note on the ./data bind mount: the image is distroless and runs as the non-root user UID 65534. Tokens are persisted to the host-mounted ./data directory, so it must be writable by that UID or token persistence fails on first run:

mkdir -p data
sudo chown -R 65534:65534 data

Alternatively, swap the bind mount for a named volume in docker-compose.yml (e.g. strava-data:/app/data), which Docker initializes with the correct ownership.

Verifying the image

Each published image carries a BuildKit SBOM and SLSA provenance in its index, plus a Sigstore-backed provenance attestation bound to the release workflow's identity:

# Signed provenance — proves which workflow and commit built this image
gh attestation verify oci://ghcr.io/ljcl/strava-mcp:latest --repo ljcl/strava-mcp

# What is inside it
docker buildx imagetools inspect ghcr.io/ljcl/strava-mcp:latest --format '{{ json .SBOM }}'
docker buildx imagetools inspect ghcr.io/ljcl/strava-mcp:latest --format '{{ json .Provenance }}'

The SBOM also feeds vulnerability scanners directly (Trivy, Grype, Docker Scout), so they can read the recorded package list instead of re-deriving one from the image.

4. Authorize with Strava

Visit https://your-public-url/auth/start in your browser. After authorizing, tokens are saved automatically.

Check status anytime at https://your-public-url/auth/status.

If you set MCP_AUTH_TOKEN (recommended for tunnel-exposed servers — see Securing the endpoint), append it to both URLs as ?token=<MCP_AUTH_TOKEN>.

Health check

GET /health reports server state without spending a Strava API request — it is served entirely from local state, so it is safe to poll. The container's HEALTHCHECK uses it.

Unauthenticated callers get liveness only:

{ "status": "ok", "version": "2.8.0", "uptime_seconds": 5 }

With MCP_AUTH_TOKEN (Authorization: Bearer <token> or ?token=<token>) — or on any server that has no secret configured — it also reports auth and rate-limit state:

{
  "status": "ok",
  "version": "2.8.0",
  "uptime_seconds": 5,
  "authenticated": false,
  "token_expires_at": null,
  "rate_limit": null
}

rate_limit is a snapshot from the most recent Strava response, so it stays null until the server has made one. The split matters when wiring monitoring: point an uptime check at the unauthenticated shape, and send the secret only when you actually want token and quota detail.

5. Connect to Claude Desktop

Add to your Claude configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "strava": {
      "type": "url",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

The headers entry is only needed when MCP_AUTH_TOKEN is set (recommended for tunnel-exposed servers — see Securing the endpoint).

Restart Claude Desktop to load the new configuration.

Using a different MCP client? See Client configuration for Claude Code, Cursor, and VS Code.

Connecting to AI Tools

Most AI tools (Claude Desktop, Claude Code, etc.) need an HTTPS URL to reach your MCP server. Since the server runs on your local network, you'll need a tunnel to expose it.

Tailscale Funnel (Recommended)

Tailscale Funnel exposes a local port to the internet over HTTPS with no configuration:

tailscale funnel --bg 3000
# → https://your-machine.tail1234.ts.net

Set PUBLIC_URL in your .env to the resulting URL.

Cloudflare Tunnel

cloudflared tunnel --url http://localhost:3000

Securing the endpoint

A tunnel makes /mcp reachable by anyone who discovers the URL — including the update-activity write tool. Set MCP_AUTH_TOKEN to a long random secret (e.g. openssl rand -hex 32) and the server requires Authorization: Bearer <token> on every /mcp request, returning 401 otherwise. Each client snippet below shows where the header goes. Without MCP_AUTH_TOKEN the endpoint stays open (unchanged behaviour) and the server logs a startup warning when PUBLIC_URL is configured.

Set it in .env alongside your Strava credentials — docker-compose.yml forwards it to the container automatically:

MCP_AUTH_TOKEN=your-long-random-secret

If you run the published image without this compose file, pass the variable through yourself (docker run -e MCP_AUTH_TOKEN=...); a server that never receives it starts with the endpoint open.

The secret also gates the OAuth web routes: /auth/start and /auth/status require it (in the browser, open /auth/start?token=<MCP_AUTH_TOKEN>), so a stranger cannot start an authorization flow against your server or read your athlete id and token expiry. /auth/callback stays open for Strava's redirect but only accepts callbacks carrying the single-use state nonce minted by your own /auth/start, so it cannot be used to overwrite your stored tokens with someone else's account.

Architecture

AI Tool (Claude Desktop, Claude Code, etc.)
    │  HTTPS
HTTPS Tunnel (Tailscale / Cloudflare)
    │  HTTP (localhost:3000)
Strava MCP Server (Docker / Bun)
    │  HTTPS
Strava API

Client configuration

The server works with any MCP client that supports the Streamable HTTP transport. In every snippet below, replace https://your-public-url with your tunnel URL (or http://localhost:3000 for local development), and include the Authorization header only if you set MCP_AUTH_TOKEN.

Claude Code

claude mcp add --transport http strava https://your-public-url/mcp \
  --header "Authorization: Bearer your-mcp-auth-token"

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "strava": {
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

VS Code

Add to .vscode/mcp.json in your workspace (or run MCP: Add Server from the command palette):

{
  "servers": {
    "strava": {
      "type": "http",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

Other clients (generic Streamable HTTP)

Any client that speaks Streamable HTTP can connect to the /mcp endpoint directly:

• POST JSON-RPC messages to https://your-public-url/mcp with an Accept: application/json, text/event-stream header.
• If MCP_AUTH_TOKEN is set, also send Authorization: Bearer <token> on every request.
• The initialize response includes an Mcp-Session-Id header; echo it on every subsequent request in the same session.

Tool permissions

Every tool declares MCP annotations so a host can tell reads from writes. The 35 read tools set readOnlyHint: true and destructiveHint: false, which is the combination clients use to offer a durable "always allow". Six tools are writes and are expected to keep asking:

No tool sets anthropic/requiresUserInteraction, so nothing here opts out of "always allow" on purpose.

If a client re-prompts for read tools after you granted them, check whether the server was upgraded to a version that renamed a tool or changed its input schema — permission grants are stored per tool identity, so that drops the grant. Releases that do this say so in the changelog. Beyond that, permission persistence lives in the client, not in this server; the connector-level and per-tool settings are both worth checking, since granting at the connector level does not always write through to every tool.

Using alongside the official Strava MCP

Strava's official MCP connector handles activity discovery and basic reads. This server supplements it with everything the official connector does not offer: writing to activities, segments, routes and GPX/TCX export, photos, derived analysis, and interactive visualizations.

Install both

• Official: claude mcp add --transport http strava-mcp https://mcp.strava.com/mcp (or via claude.ai Connectors / Claude Desktop).
• This server: see the install steps above.

Who does what

Caveats

• The official connector requires a Strava subscription and currently runs only in Anthropic clients.
• With the duplicate reads removed, this server now effectively assumes the official connector is installed for activity discovery. The aggregate analysis tools (get-best-efforts, get-training-load) fetch their own activity lists, but per-activity tools (get-running-summary, compare-activities, get-activity-zones, etc.) need an activity id from the official list_activities.
• The two use separate rate-limit quotas, so running both spreads API load.

Recommended workflow

Use the official connector to discover and read activities, then use this server to write, explore segments, manage and export routes, and visualize. The model can pass activity ids from official list_activities directly into this server's tools.

Local Development

For running without Docker or Tailscale Funnel:

Prerequisites

• Bun runtime
• A Strava Account

Setup

bun install

# Run the setup script for localhost-based OAuth
cd apps/server
bun run setup-auth

# Start the development server (server + MCP App watchers)
cd ../..
bun run dev

The setup script will guide you through the OAuth flow using localhost as the redirect URI.

Configure Claude Desktop (Local)

{
  "mcpServers": {
    "strava": {
      "type": "url",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Environment Variables

*Required for Docker/web-based OAuth. Not needed when using bun run setup-auth locally.

Token Handling

The server implements automatic token management:

• On startup: Checks token validity and refreshes if expired
• During operation: Automatically refreshes on 401 errors
• Persistence: Tokens are saved to data/tokens.json (survives container restarts)
• Re-authorization: Visit /auth/start anytime to re-authorize

You only need to authorize once per scope set. The refresh token obtains new access tokens automatically, but it cannot add scopes that were not granted originally.

Re-authorizing after a scope change

When the server gains a tool that needs a new OAuth scope (for example activity:write for editing activities), you must do a fresh authorization to mint a token that carries it. The automatic refresh keeps the old scopes.

• Local: cd apps/server && bun run setup-auth
• Web / Docker: visit /auth/start on your server

Both flows use approval_prompt=force, so Strava re-prompts and issues a token with the current scope set.

Rate Limits & Resilience

The HTTP layer (apps/server/src/fetchClient.ts) handles Strava's rate limits and transient failures centrally, so every tool benefits without per-tool code:

• Rate-limit awareness: Every response's X-RateLimit-* / X-ReadRateLimit-* (15-minute and daily windows) and Retry-After headers are parsed. Strava allows 100 requests / 15 min and 1000 / day by default (docs).
• 429 backoff: On a rate-limit response the client honours Retry-After and retries (bounded, so a tool call never blocks on a full 15-minute window). When the limit is genuinely exhausted the model gets a structured message naming which window is gone and when it resets.
• Transient retry: 5xx (500/502/503/504) and network faults are retried with bounded exponential backoff. Only idempotent reads (GET) are retried; writes (update-activity, star-segment) are never blindly retried.

This is passive — there's nothing to configure. To see where you currently stand, read rate_limit from /health: it reports the snapshot parsed from the most recent Strava response, without spending a request of its own.

Natural Language Examples

Ask your AI assistant questions like these (use the official Strava MCP to discover activity IDs, then pass them to these tools):

Activity Writing:

• "Update the title of activity 12345678 to 'Morning Threshold'"
• "Add a note to my last ride: 'Felt strong on the climbs'"

Analysis and Visualization:

• "Show me the HR zone breakdown for activity 12345678"
• "Compare my two long runs from last week"
• "What are my best 5K and mile efforts?"
• "Show me the cadence trends for my last 10 runs"
• "View the route map for my last ride"
• "Show me the segments from this morning's run"

Stats:

• "What are my running stats for this year on Strava?"

Segments:

• "List the segments I starred near Boulder, Colorado"
• "Get details for the 'Alpe du Zwift' segment"
• "Star the 'Flagstaff Road Climb' segment for me"
• "Am I getting faster on segment 8109834? Show my effort history"
• "Star the climbs on my goal race course, then review my progress on them each month"

Training analysis:

• "Break down the intervals in activity 12345678 — did I fade across the reps?"
• "How much did the climbs cost me on Sunday's long run?"
• "Did I positive-split Sunday's long run, or was that just the hills?"
• "Show me the mile splits for activity 12345678 with grade-adjusted pace"
• "Am I fresh enough to race this weekend? Check my CTL, ATL, and TSB"
• "My race is on 13 September — what should the next three weeks look like so I arrive at TSB +10?"
• "Chart my fitness and fatigue for the season and show the taper to race day"
• "Did I decouple on that marathon-pace effort?"

Routes:

• "List my saved Strava routes"
• "Export my 'Boulder Loop' route as a GPX file"
• "Map my race route with fuel stops at 10k, 21k, and 32k, and flag the climb at 28k"

MCP Prompts

Beyond tools, the server exposes three prompts — reusable multi-step workflows a host can offer as slash commands or starters, so the user does not have to compose the tool calls themselves.

In Claude Desktop and Claude Code these appear in the prompt picker once the server is connected. annotate-last-run and segment-hunt use write tools (update-activity, star-segment), so they need the activity:write scope.

API Reference

The server exposes the following MCP tools:

Activity Tools

Athlete Tools

Segment Tools

Route Tools

Visualization Tools

Project Structure

apps/server/                 MCP server (tools, auth, token management)
apps/storybook/              Storybook for UI development
packages/activity-chart/     Interactive activity chart (MCP App)
packages/cadence-trends/     Cadence trend analysis (MCP App)
packages/route-map/          Activity/route GPS map (MCP App)
packages/activity-segments/  Activity segment-effort list (MCP App)
packages/training-load/      Weekly training volume and trend (MCP App)
packages/compare-activities/ Two-activity stream overlay (MCP App)
packages/activity-zones/     Per-activity time-in-zone chart (MCP App)
packages/segment-progress/   Segment effort history (MCP App)
packages/fitness-trend/      Fitness/fatigue/form chart with taper plan (MCP App)
packages/data/               Shared pure data utilities
packages/ui/                 Shared presentational React components
packages/design-system/      Design tokens, color constants, Storybook preview
packages/vite-config/        Shared Vite config for MCP App builds
packages/tsconfig/           Shared TypeScript configurations

Development

Bun workspaces with Turborepo. All tasks are cached and run in parallel where possible.

bun run check             # Full verification: lint + test + typecheck + build + boundaries
bun run check:affected    # Same, only packages changed since main
bun run build             # Build all packages
bun run test              # Run all tests
bun run lint              # Lint (Biome)
bun run lint:fix          # Auto-fix lint issues
bun run knip              # Dead code / unused export analysis
bun run boundaries        # Package boundary enforcement
bun run dev               # Dev mode (server + MCP App watchers)

# Storybook
cd apps/storybook
bun run storybook         # Storybook on port 6006

Storybook and visual review

The UI packages are developed in Storybook (apps/storybook). The main build is published to GitHub Pages. Every pull request runs the stories as automated tests: each story renders in headless Chromium via Vitest browser mode and passes an axe accessibility pass, and stories with a play function assert component behaviour in the same run. To review a branch's UI visually, check it out and run bun run storybook.

Storybook also exposes a Model Context Protocol server (via @storybook/addon-mcp) so AI tools can read component docs and stories. The endpoint is pre-wired in .mcp.json: a local one at http://localhost:6006/mcp (while Storybook is running).

See CLAUDE.md for the full architecture reference, styling guide, Turborepo details, and MCP App patterns.

Commits and releases

PRs are squash-merged, so the PR title becomes the commit on main. Write it as a Conventional Commit:

• feat: ... — minor version bump
• fix: ... — patch version bump
• feat!: ... or a BREAKING CHANGE: footer — major version bump
• chore: / docs: / refactor: / ci: — no release

A CI check (pr-title.yml) rejects non-conforming PR titles. Versioning, the changelog, and image publishing are automated by release-please; a non-conventional title means no release is cut.

Troubleshooting

AI tool can't reach the server — MCP requires an HTTPS URL. Use a tunnel (Tailscale Funnel or Cloudflare Tunnel) to expose your local server. See Connecting to AI Tools.

OAuth callback fails — Ensure PUBLIC_URL in your .env matches the tunnel URL exactly, and that the same hostname is set as the "Authorization Callback Domain" in your Strava API settings.

Token errors or expired tokens — Check /health first: authenticated and token_expires_at tell you whether the server holds a usable token, which separates an auth problem from a reachability one. Then visit /auth/start to re-authorize. Tokens are refreshed automatically, but a full re-auth may be needed if the refresh token has been revoked. See Health check.

Is the server up and reachable? — curl https://your-public-url/health. It answers without touching the Strava API, so it works even when your rate limit is exhausted.

Tokens don't survive a container restart (Docker) — The container runs as non-root UID 65534, so the ./data bind mount must be writable by that UID (sudo chown -R 65534:65534 data) or use a named volume instead. See Quick Start step 3.

License

MIT