Strava Planner

A personal, read-only MCP server that exposes Strava training data to Claude. It supports:

• Local stdio for MCP clients that can spawn a process.
• Authenticated Streamable HTTP at /mcp for Claude Web and other remote MCP clients.
• Docker deployment behind an HTTPS-terminating Nginx reverse proxy.

The server retrieves and reshapes data. Claude performs coaching, planning, and analysis.

Architecture

Claude Web
  -> HTTPS Streamable HTTP + OAuth 2.1
  -> Nginx
  -> 127.0.0.1:8000
  -> Docker: TypeScript MCP server
  -> Strava REST API

The remote transport is stateless Streamable HTTP. This keeps a single-instance personal deployment simple and avoids sticky-session requirements. Stdio remains available through npm start.

Requirements

• Node.js 20 or newer for local development.
• A Strava API application.
• Docker and Docker Compose for deployment.
• A DNS name and trusted HTTPS certificate for Claude Web.
• Claude Pro, Max, Team, or Enterprise with custom connectors enabled.

Install And Test

npm ci
npm run typecheck
npm test
npm run build

Strava Configuration

Create an application at https://www.strava.com/settings/api. Local browser authorization uses these scopes:

• read
• activity:read_all
• profile:read_all

Copy the environment example:

cp .env.example .env

Generate independent secrets:

openssl rand -base64 32
openssl rand -hex 16
openssl rand -base64 48
openssl rand -base64 48

Use them for STRAVA_TOKEN_ENCRYPTION_KEY, MCP_OAUTH_CLIENT_ID, MCP_OAUTH_CLIENT_SECRET, and MCP_OAUTH_TOKEN_SIGNING_KEY respectively.

There are two ways to seed Strava authorization:

1. Set STRAVA_REFRESH_TOKEN from the Strava API application page. On first API use, the server exchanges it and writes the current token set to the encrypted token file.
2. Run npm run auth on a machine with a browser, then preserve the generated encrypted token file and the same encryption key.

The encrypted token file takes precedence over STRAVA_REFRESH_TOKEN. When Strava rotates the refresh token, the new token is encrypted and persisted. In Docker it lives in the strava-mcp-data volume.

Token Persistence, Backup, And Recovery

The encrypted token file is written atomically (temp file, fsync, then rename) with 0600 permissions, so an interrupted write can never truncate the only good copy. Concurrent refreshes within the process are serialized.

Because Strava rotates refresh tokens, this file is the source of truth once seeded. If it becomes corrupt or is decrypted with the wrong key, the server fails loudly with a clear operational error and does not overwrite it — so recoverable state is never silently destroyed.

• Back up the encrypted token file together with the exact STRAVA_TOKEN_ENCRYPTION_KEY (the file is useless without the key). In Docker, back up the strava-mcp-data volume.
• Recover by restoring the file and key, or by re-seeding: set a fresh STRAVA_REFRESH_TOKEN (or run npm run auth) and delete the unreadable file so the seed path can run.
• Losing both the file and a valid seed refresh token means re-authorizing Strava from scratch.

Environment Variables

Required for all modes (STRAVA_REFRESH_TOKEN may be omitted when a valid encrypted token file already exists):

Variable	Purpose
STRAVA_CLIENT_ID	Strava application client ID.
STRAVA_CLIENT_SECRET	Strava application client secret.
STRAVA_TOKEN_ENCRYPTION_KEY	Encrypts the persisted Strava token file.
STRAVA_REFRESH_TOKEN	Seeds Docker/remote authorization if no encrypted token file exists. One of these two sources is required.

Required for authenticated remote mode:

Variable	Purpose
MCP_PUBLIC_URL	Exact public endpoint, e.g. https://mcp-strava.example.com/mcp.
MCP_OAUTH_CLIENT_ID	Fixed OAuth client ID entered in Claude.
MCP_OAUTH_CLIENT_SECRET	Fixed OAuth client secret entered in Claude.
MCP_OAUTH_TOKEN_SIGNING_KEY	Signs MCP access and refresh tokens.

Important optional variables:

Variable	Default
MCP_HOST	0.0.0.0 (production behind Nginx). Use 127.0.0.1 for authless local dev.
MCP_PORT	8000
MCP_AUTH_ENABLED	true
MCP_ALLOW_INSECURE_BINDING	false. When true, permits authless mode on a non-loopback host.
MCP_ALLOWED_HOSTS	Public hostname plus localhost names.
MCP_TRUST_PROXY	true
MCP_OAUTH_REDIRECT_URIS	https://claude.ai/api/mcp/auth_callback
STRAVA_TOKEN_PATH	~/.strava-planner-mcp/tokens.enc.json outside Docker; /data/tokens.enc.json in Compose.
ATHLETE_CONTEXT_PATH	Unset outside Docker; /config/athlete-context.json in Compose.
STRAVA_CACHE_TTL_SECONDS	900
STRAVA_CACHE_MAX_ENTRIES	500 (bounded LRU cache size).
STRAVA_MAX_RETRIES	4
STRAVA_REQUEST_TIMEOUT_MS	30000
HALF_MARATHON_TRAINING_START_DATE	Unset. Optional YYYY-MM-DD fallback for getHalfMarathonTrainingContext.

Production-critical secrets (STRAVA_CLIENT_SECRET, STRAVA_TOKEN_ENCRYPTION_KEY, MCP_OAUTH_CLIENT_SECRET, MCP_OAUTH_TOKEN_SIGNING_KEY) are validated at startup: the server refuses to boot if they still contain the .env.example placeholder text, and the signing/encryption/OAuth secrets must be at least 16 characters.

See .env.example for the complete list, grouped by local-dev / Docker / production.

Local Linux Development

For a quick authless loopback test, set this only in a development .env:

MCP_AUTH_ENABLED=false
MCP_HOST=127.0.0.1
MCP_ALLOWED_HOSTS=localhost,127.0.0.1

Authless mode refuses to start on a non-loopback host (MCP_HOST other than 127.0.0.1/::1/localhost) so it cannot accidentally expose unauthenticated tools to the LAN. Override deliberately with MCP_ALLOW_INSECURE_BINDING=true only if you know what you are doing.

Start Streamable HTTP:

npm run dev:http

Check liveness and readiness:

curl http://127.0.0.1:8000/health   # cheap liveness, always 200 when running
curl http://127.0.0.1:8000/ready    # 200 only when a usable Strava token source exists

Run the official MCP Inspector:

npm run inspect:http

Select Streamable HTTP and use http://127.0.0.1:8000/mcp.

Do not use MCP_AUTH_ENABLED=false on a public interface. To test OAuth locally, use MCP_PUBLIC_URL=http://localhost:8000/mcp and configure all MCP_OAUTH_* values.

For stdio debugging:

npm run dev
# or, after npm run build
npm start

Personal Athlete Context

Optional goals, heart-rate zones, constraints, and preferences live outside source code. Create the local file:

cp config/athlete-context.example.json config/athlete-context.json

Edit it as needed. getAthleteContext returns it to Claude. The actual file is gitignored and mounted read-only in Docker.

Docker Deployment

The image uses the multi-architecture node:22-bookworm-slim base and works on ARM64/aarch64.

Production deployment on the VM (GHCR image + central proxy) is documented step-by-step in DEPLOY.md. In short: GitHub Actions (.github/workflows/build.yml) builds and pushes ghcr.io/mohith1612/strava-planner-mcp (multi-arch, incl. linux/arm64); the VM runs compose.prod.yaml on the shared proxy network with no published ports, and proxy_nginx reaches it by container name.

For a local Docker smoke test (builds the image locally, publishes on loopback):

docker compose build
docker compose up -d
docker compose ps                       # "healthy" once /ready passes
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/ready
docker compose logs -f strava-mcp
docker compose down                     # add -v ONLY to delete the token volume

The container HEALTHCHECK polls /ready (which verifies a usable token source without calling Strava). The container runs as the non-root node user, drops Linux capabilities, enables no-new-privileges, and handles SIGTERM.

Nginx And HTTPS

On the VM, Nginx is the shared central proxy at /opt/proxy/. Drop nginx/strava-mcp.conf.example in as /opt/proxy/nginx/conf.d/strava.conf (it already targets strava.mohith16.com → strava_mcp:8000) and reload:

docker compose -f /opt/proxy/docker-compose.yml exec nginx nginx -t
docker compose -f /opt/proxy/docker-compose.yml exec nginx nginx -s reload

The config proxies all paths (including /.well-known/oauth-* and /mcp) to the container over the proxy network using the resolver 127.0.0.11 + set $upstream pattern, disables buffering, and uses long streaming timeouts. The shared *.mohith16.com wildcard cert already covers the subdomain, so no new certificate is required. Do not expose container port 8000 publicly.

After DNS + TLS are live, verify:

curl https://strava.mohith16.com/health
curl https://strava.mohith16.com/ready
curl -i https://strava.mohith16.com/mcp
curl https://strava.mohith16.com/.well-known/oauth-protected-resource/mcp
curl https://strava.mohith16.com/.well-known/oauth-authorization-server

An unauthenticated /mcp request should return 401 with a WWW-Authenticate resource metadata link.

Connect Claude Web

1. Open Claude → Settings → Connectors.
2. Click Add custom connector.
3. Name it Strava Planner.
4. Set the remote MCP server URL to https://strava.mohith16.com/mcp.
5. Open Advanced settings.
6. Enter the exact MCP_OAUTH_CLIENT_ID and MCP_OAUTH_CLIENT_SECRET from the server .env.
7. Click Add, then Connect.
8. Enable the desired Strava tools in the Search and tools menu.

The URL entered in Claude must match MCP_PUBLIC_URL exactly, including the /mcp path and with no trailing slash. Access tokens are bound to that exact resource (RFC 8707 audience), so a mismatch is rejected. The redirect URI Claude uses is https://claude.ai/api/mcp/auth_callback, which is the default in MCP_OAUTH_REDIRECT_URIS.

The OAuth flow uses Claude's callback URL, PKCE (S256), a fixed confidential client authenticated with client_secret_post, one-hour signed access tokens, rotating 30-day refresh tokens, and MCP protected-resource + authorization-server metadata discovery. Claude supports this static-client model natively — the OAuth Client ID/Secret fields in Advanced settings exist precisely so a server can skip Dynamic Client Registration.

Tools

Existing tools remain available:

• getAthleteProfile
• getActivities
• getActivity
• getActivityStreams
• getRecentActivities
• getActivitiesByType — paginated: accepts after, before, page, and limit (max 200), and returns a nextPage hint.
• getTrainingHistory — paginated: accepts after, before, page, and limit (max 200), returns newest-first with a nextPage hint.
• getAthleteOverview — bounded to a look-back window (sinceDays, default 365) instead of the full history.
• getHalfMarathonTrainingContext

Additional detailed-analysis tools:

• getActivityLaps
• getActivityZones
• getRecentRuns
• getAthleteContext

Pagination change (backward-compatible defaults): getActivitiesByType and getTrainingHistory previously returned the athlete's entire history in one response. They now return one bounded page and expose nextPage; call again with that value to page through older activities. This keeps responses small and predictable.

Tool results are returned as pretty-printed JSON text content. Structured output schemas were intentionally not adopted to keep Claude Web operation maximally reliable; response size is controlled by the pagination above.

getHalfMarathonTrainingContext window

The training-cycle start date is resolved in this order: trainingStartDate in the athlete context file, then HALF_MARATHON_TRAINING_START_DATE, then a trailing 26-week window. Optional targetRaceDate, targetDistance, and targetTime in the athlete context are surfaced in the report. Weekly buckets use athlete-local time (Strava start_date_local) with Monday week starts, and every calendar week in the range is represented so streak and consistency metrics never bridge an inactive week.

getActivityStreams accepts streamTypes, allowing requests such as:

{
  "activityId": 123456789,
  "streamTypes": ["time", "distance", "heartrate", "velocity_smooth", "cadence"]
}

Supported streams are time, distance, latlng, altitude, velocity_smooth, heartrate, cadence, watts, temp, moving, and grade_smooth. Strava returns only streams available for that activity.

Caching And Rate Limits

• Activity responses use a bounded in-memory TTL + LRU cache per process (STRAVA_CACHE_MAX_ENTRIES, default 500). Expired entries are pruned lazily and on write, and the least-recently-used entry is evicted past the cap, so memory cannot grow unbounded.
• Historical data is not persisted in a database.
• Multi-page fetches are capped (getAllActivities never exceeds 25 pages) and the history tools page explicitly.
• Transient failures and 429/5xx responses use exponential backoff with jitter; Retry-After is honored in both integer-seconds and HTTP-date forms.
• The Strava OAuth token exchange and refresh now also have a request timeout and transient-failure retry; a permanent 4xx is returned immediately.
• A single 401 triggers one refresh-and-retry; permanent 4xx responses are returned immediately rather than retried.
• Strava token refreshes are serialized (single-flight) to prevent concurrent rotation races.

SQLite was deliberately not added. For a single-user instance, the current cache avoids repeated calls within a session while keeping the ARM64 image and operational model small.

Security Status

Production protections implemented:

• OAuth-compatible Claude Web authentication with PKCE (S256) and refresh-token rotation.
• MCP access and refresh tokens signed with HS256; access tokens are audience-bound to the exact MCP URL.
• Encrypted Strava tokens at rest with AES-256-GCM, written atomically with 0600 permissions.
• Startup validation rejects placeholder/short production secrets.
• Authless mode fails closed on any non-loopback bind unless explicitly overridden.
• Read-only MCP tools with bounded, paginated responses.
• HTTPS enforced at Nginx with HSTS, X-Frame-Options, X-Content-Type-Options, and modern TLS ciphers.
• Host-header allowlist and DNS-rebinding protection from the MCP SDK.
• OAuth endpoint rate limiting supplied by the MCP SDK.
• No secrets or Strava payloads in normal logs.
• Non-root container, dropped capabilities, no-new-privileges, and localhost-only published application port.

Single-user limitations:

• Dynamic Client Registration is intentionally disabled; enter the fixed client credentials in Claude.
• A valid fixed client authorization request is approved immediately; there is no separate human consent page. Security therefore depends on keeping the OAuth client secret private and serving only over HTTPS.
• Token revocations are remembered in memory. A restart clears the revocation set, although signed tokens still expire normally. Rotate MCP_OAUTH_TOKEN_SIGNING_KEY to invalidate every outstanding MCP token immediately.
• The in-memory cache is not shared across replicas. Run one container unless you add shared state.

Never publish the endpoint with MCP_AUTH_ENABLED=false. GPS routes and heart-rate data are private and may be returned by tools.