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.

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

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

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

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

• 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

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.

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

• The Worker validates Cloudflare Access assertions before reading R2.

• 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.

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. See HRV and sleep history for date-range behavior, monthly R2 indexes and the one-time index build.

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.

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 generates coach input for refreshed running activities. Therefore data_ready means these related R2 outputs have finished—not merely that the summary CSV was written. 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.

Coach generation runs as a separate R2-only consumer after activity-producing workflows. It keeps a per-activity source index, so unchanged FIT/TCX artifacts are not reread on every historical backfill cycle.

Manual refresh:

gh workflow run refresh.yml

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

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.