Slipstream Extended

A private, self-hosted MCP server for exploring your Garmin history with an AI assistant.

Slipstream Extended imports data from Garmin Connect, stores it in your own private Cloudflare R2 bucket, and exposes safe, analysis-oriented tools through a Cloudflare Worker. Cloudflare Access Managed OAuth controls who may connect. There is no shared Slipstream service: every user installs and pays for their own infrastructure.

Use it to discuss your latest workout, last night's recovery, training trends and weight history in ChatGPT or another compatible assistant. Fresh-data requests check what is already stored, import only the needed recent scope when necessary, and report whether the requested data is ready. Your historical data and prepared analyses remain available between refreshes.

What it includes

• Activity and daily-health summaries

• Minute-level overnight HRV curves

• Sleep stages, sleep score components, respiration, SpO2 and stress

• Bounded HRV and sleep history with automatic weekly summaries for long ranges

• Weight and body-composition measurements, plus bounded morning-weight history

• Optional revision-verified monthly weight indexes retaining all weighings and clocks

• Strength exercises, sets, reps, weight, work time and rest time

• Endurance laps, kilometre splits, heart-rate distribution and drift

• Optional aerobic/anaerobic Training Effect from verified stored FIT sessions in activity detail reads

• Versioned coach profiles, append-only RPE/context and prepared coach-input JSON

• Optional encrypted local backup and isolated recovery testing of user-owned profile/context history and immutable coach inputs; see the backup quick start for a separate local installation

• Resumable historical backfills that become read-only checks when complete

• Detection and replacement of changed Garmin activity files

• Optional chat-triggered refresh with completion polling

• R2-first fresh workout and sleep/HRV requests with bounded targeted imports

Raw FIT/TCX files remain private in R2. MCP tools never return GPS coordinates, routes, arbitrary R2 objects or Garmin credentials.

Related MCP server: garmin-givemydata

Architecture

Garmin Connect
      │ read-only session token
      ▼
GitHub Actions ── restore / merge / upload ──► private Cloudflare R2
                                                      │ private binding
                                                      ▼
AI client ◄── MCP + Managed OAuth ── Cloudflare Access ── Worker

• GitHub Actions supplies scheduled compute; generated fitness data is not committed to Git.

• Chat dispatch, schedules and local refresh share one bounded Python pipeline, with per-stage timing and provider/storage call counts for troubleshooting.

• Refresh stages reuse one R2 client and lazy bucket inventory per run, retaining separate stage write limits and conservative storage accounting across stages. Pipeline writers share one queue; each new run checks current storage again.

• R2 is the source of truth for summaries, detailed exports and backfill state.

• The Worker validates Cloudflare Access assertions before reading R2.

• Its shared storage reader bounds payloads and checks summary revisions before reusing parsed data, so warm chats see updated imports.

• Sleep/HRV and activity/coach tools live in focused modules with shared storage and unchanged tool contracts, making the connector easier to maintain.

• A rate limiter, payload bounds and a Durable Object refresh lease protect the installation from abuse and duplicate dispatches.

See Architecture for the complete flow.

Install

Each installation needs its own Garmin, GitHub and Cloudflare accounts, plus an OAuth-capable MCP client. The documented and tested client flow uses ChatGPT.

Start with the complete installation guide. It covers R2, GitHub secrets, Garmin login, Worker deployment, Cloudflare Access, Managed OAuth, redirect URIs, testing and cost checks.

./setup.sh is a safe bootstrap helper for macOS/Linux, and setup-windows.ps1 provides the equivalent native PowerShell flow on Windows. Both check prerequisites and install local dependencies, but deliberately leave account-specific R2 credentials and Access policy decisions to the documented dashboard steps.

Both also run a read-only installation check that points to the next unfinished step. Rerun python scripts/check_installation.py to resume; optional --online checks verify your own cloud setup without changing credentials or data. Recent data is sufficient to finish setup; full historical backfill remains optional.

Connect and use

The canonical server URL is:

https://<worker-name>.<workers-subdomain>.workers.dev/mcp

It is protected by Cloudflare Access Managed OAuth. There is no secret URL and no unauthenticated fallback. See Connecting an MCP client.

Example questions:

• “How has my running volume changed over the last eight weeks?”

• “Show last night's HRV curve and compare it with my recent baseline.”

• “Summarize my latest strength session by exercise and category.”

• “Analyze the latest run for splits, heart-rate drift and time at each BPM.”

• “Save my confirmed running zones, then prepare coach input for my latest run.”

• “Refresh today's Garmin data, wait until it is ready, then summarize it.”

More examples are in Prompt ideas. Start with the copyable AI workflows for the six common tasks and consult the generated MCP tool catalog for actual registrations, input limits and conditional permissions. For an explicitly requested update, sync_latest_activity and sync_latest_night check canonical R2 data and a recent successful source check before starting a targeted import. They report source age, missing components and readiness, and share compatible jobs. Historical read tools stay read-only. See Fresh data on request for local workout/wake-date rules, polling limits and R2-only Coach Input repair. See HRV and sleep history for date-range behavior, local night_of versus wake-date semantics, monthly R2 indexes and the one-time index build. Garmin's recorded local times handle travel nights; set HEALTH_TIMEZONE during installation as a DST-correct fallback for older data.

Keeping data fresh

The summary workflow runs every six hours. Detailed health and activity jobs are staggered and serialized so Garmin is never queried concurrently. Historical backfills skip existing objects, persist progress, pause repeated item failures, and quiesce automatically when complete.

Historical activity discovery resumes bounded metadata pages and pending imports from the existing range progress. It preserves accumulated failure counts and the three-failure automatic retry threshold. Checkpoint wire version 2 reads older state, but rolling back to an older reader needs preserved compatible progress. See activity backfill for limits, reconciliation, compatibility and measured resource tradeoffs.

Each six-hour summary refresh also refreshes the three most recent HRV and detailed-sleep dates. A chat-triggered refresh performs the same recent-health steps, checks recent activity artifacts and prepares coach input for selected new/recent running activities. Unchanged activity files and ready analyses are reused; unchanged summaries and same-day snapshots skip uploads. Recent source data is still checked so late changes can be reconciled.

Summary publication now seals immutable activity/health pairs before committing a conditional manifest. Cold Python refreshes can recover that committed pair after an interrupted upload; existing current-CSV consumers retain their compatibility interface. See summary recovery for legacy fallback, retry limits, storage cost and rollout boundaries.

Recent sleep and HRV also reuse unchanged canonical files and monthly indexes, updating only affected months. Successful source-check times are recorded separately; empty or incomplete Garmin responses preserve earlier usable data. Targeted night refresh shares this import logic. General manual refresh leaves sleep/HRV historical plans untouched, while scheduled index reconciliation and explicit backfills remain available. See fresh-data behavior for the retained overlap and request-volume measurements.

General manual and scheduled refresh also recheck the three latest populated weight dates and reuse unchanged individual weigh-in files. Every actual sample, timestamp and composition field is retained; successful source checks advance separately. Sparse weigh-ins retain an overlap of measured dates. Historical body backfill plans remain untouched, and incomplete dayviews preserve earlier data.

General summary refresh normally checks the past week of activities, with an inclusive overlap day, and three health dates. A successful wider check permits these shorter repeats for 24 hours; the next refresh then rechecks the existing 30-day activity and 14-day health windows. Missing or failed wider checks remain due. Older summary rows are retained, and edits within the wider windows are picked up by this daily reconciliation. Detailed health checks and explicit historical imports keep their own scopes. See fresh-data behavior for the coverage limits and measured request/storage tradeoffs.

Scheduled sleep/HRV index maintenance checks recent calendar months rather than scanning all history every six hours. It performs a full R2 repair at startup and when the last successful full check is at least seven days old. Missing or failed checks remain due, and immediate manual full repair remains available. This repairs indexes from stored data; it does not re-download Garmin history. See health-history maintenance for recovery and reproducible operation counts.

data_ready reports workflow completion. Check each activity's files_ready and coach_status before claiming its files and analysis are ready. A configured coach profile and usable endurance artifacts are still required for an analysis.

For a new installation with years of history, an optional local overnight bootstrap can advance the same R2 plans in consecutive bounded cycles. It is resumable, retains all free-tier guards, and requires the scheduled cloud jobs to be paused while it runs. The same local tooling can seed canonical HRV and sleep objects from existing raw Garmin JSON exports, skipping anything already present in R2.

Historical coach generation runs as a separate R2-only consumer after scheduled refresh and other activity-producing workflows. Manual refresh prepares its selected analyses directly and skips the automatic historical follow-up. The historical consumer keeps a per-activity source index, so unchanged FIT/TCX artifacts are not reread on every backfill cycle.

Manual refresh:

gh workflow run refresh.yml -f include_granular=true

Optional chat-triggered refresh requires a fine-grained, single-repository GitHub token with Actions: read and write. Store both values as Worker secrets, never in wrangler.jsonc:

cd worker
npx wrangler secret put GITHUB_REPOSITORY
npx wrangler secret put GITHUB_ACTIONS_TOKEN
npm run deploy

Use owner/repository for GITHUB_REPOSITORY. Without these optional secrets, all read tools still work and only on-demand refresh is disabled.

Free-tier design

The workflows use R2 Standard storage and fail closed before projected usage exceeds conservative project limits: 5 GiB stored, 100,000 objects, 250 writes per run and 512 MiB uploaded per run. These are below Cloudflare R2's published free allowance of 10 GB-month, 1 million Class A operations and 10 million Class B operations per month. Authenticated MCP calls are limited to 30 per minute per identity, leaving substantial room below the Workers Free daily request allowance for a personal installation.

The public template exposes only read tools by default. Installers may opt in to immutable coach-profile and append-only activity-context writes; accepted writes then have an exact 60-per-identity UTC-day ceiling in addition to short cooldowns.

Coach analysis is deliberately outside the Worker CPU path. The scheduled job uses existing R2 artifacts only, processes 50 activities per run, and is limited to 60 writes and 64 MiB per run. Historical sleep and body-composition jobs use up to 100 dates per stream while retaining the shared 250-write ceiling. The activity scheduler keeps its 50-activity Garmin limit but carries unused capacity across year boundaries. Once complete these jobs perform no further writes until a relevant source, profile or user context changes.

Standard GitHub-hosted runners are free for public repositories. Private repositories use the account's included Actions allowance. Cloudflare and GitHub can change their terms, so verify the official pages:

• Cloudflare R2 pricing

• Cloudflare Workers limits

• GitHub Actions billing

Privacy and security

• Access is allow-listed by identity in the installer's own Zero Trust account.

• The Worker verifies signature, issuer, audience, expiry and human identity.

• The Worker accepts only the configured production hostname and is read-only unless the installer explicitly enables bounded append-only tools.

• Garmin and R2 credentials stay in encrypted GitHub/Cloudflare secrets.

• R2 is private and reached through a Worker binding.

• Generated datasets and tokens are ignored by Git.

• Responses use no-store; request and object sizes are bounded.

• Refresh requests are rate-limited, cooldown-protected and atomically leased.

Read Security before making an installation available outside a personal account.

Maintenance

Shared synthetic sleep/HRV tests exercise the complete Python import, R2 objects and indexes, and authenticated MCP responses in the local Workers runtime. They cover changed data in warm chats, interrupted index updates, recovery and summary cache refresh. See health contract tests for coverage and local commands.

Dependabot proposes weekly Python, npm, Wrangler and GitHub Actions updates. Review and merge only after CI passes. A weekly upstream workflow opens or updates an issue when the original project changes. It never merges or pushes upstream code automatically; every change must be reviewed and adapted manually.

Useful documents:

• Install

• Connect

• Architecture

• Optional local overnight bootstrap

• Troubleshooting

• FAQ

• Security

• Publishing safely

• Maintainer promotion workflow

• Contributing

• Code of Conduct

Scope

Garmin does not provide an official personal API. Slipstream uses the community garminconnect library and may need maintenance if Garmin changes private interfaces. It is intentionally single-tenant and read-only with respect to Garmin.

License and non-affiliation

MIT. Slipstream Extended is an independent derivative of the original Slipstream project by Yannique Hecht. The clean public history intentionally does not claim GitHub fork ancestry. Slipstream Extended is not affiliated with or endorsed by Garmin, Cloudflare, GitHub, Anthropic or OpenAI.