FreeReps

FreeReps

Freely hosted Records, Evaluation & Processing Server

A self-hosted server that receives health data from Apple Watch and Oura Ring, stores it persistently, visualizes it through a web dashboard with freely configurable correlations, and exposes it as an MCP server for LLMs. The iOS companion app syncs HealthKit data directly to your server, and the built-in Oura integration pulls data via the Oura API.

[](https://apps.apple.com/us/app/freereps/id6760661354)

Acknowledgements

The FreeReps iOS companion app is based on HealthBeat by kempu, an open-source iOS app for syncing Apple Health data. HealthBeat was adapted into the FreeReps companion app for the self-hosted FreeReps server. Licensed under the MIT License.

Screenshots

| Dashboard | Sleep | |:-:|:-:| | | |

| Metrics | Trends | |:-:|:-:| | | |

| MCP | |:-:| | |

| iOS App | | | | |:-:|:-:|:-:|:-:| | | | | |

Why FreeReps?

Apple Health collects extensive data but offers no way to relate metrics to each other, no API for external analysis, and no export into a queryable system you own.

Other apps compute scores but are closed-source, subscription-based, and opaque. FreeReps takes the opposite approach: raw data + flexible visualization + LLM for interpretation.

Architecture

┌──────────────┐     HealthKit       ┌─────────────────────────────────────────┐
│ FreeReps     │ ────────────────→   │              FreeReps Server            │
│ iOS App      │    HTTP POST        │                                         │
└──────────────┘                     │  ┌──────────┐  ┌─────────────────┐     │
                                     │  │ Ingest   │→ │  Storage (DB)   │     │
┌──────────────┐     OAuth2 + Poll   │  │ API      │  │  Time Series    │     │
│  Oura Ring   │ ←───────────────    │  └──────────┘  └────────┬────────┘     │
│  (API v2)    │                     │  ┌──────────┐           │              │
└──────────────┘                     │  │ Oura     │→──────────┘              │
                                     │  │ Sync     │  (source-priority dedup) │
                                     │  └──────────┘                          │
                                     │              ┌──────────┬──────────┐   │
                                     │              ▼                     ▼   │
                                     │  ┌────────────────┐  ┌─────────────┐  │
                                     │  │ Web Dashboard  │  │ MCP Server  │  │
                                     │  │ Correlations   │  │ stdio / SSE │  │
                                     │  │ Trends, Charts │  └──────┬──────┘  │
                                     │  └────────────────┘         │         │
                                     └─────────────────────────────┼─────────┘
                                                                   ▼
                                                          Claude (via MCP)
                                                          = the actual
                                                            "AI coach"

Tech Stack

| Component | Technology | |-----------|------------| | Backend | Go (single binary with embedded frontend) | | Frontend | React 19 + Vite + Tailwind CSS 4 | | Charts | uPlot (time-series) + Recharts (bar/scatter) | | Database | PostgreSQL + TimescaleDB | | Auth & Networking | Tailscale (tsnet) — zero-config TLS + identity | | iOS App | Swift (HealthKit, BackgroundTasks, ActivityKit) | | Config | YAML | | Deployment | Docker Compose |

iOS Companion App

The FreeReps companion app syncs Apple HealthKit data directly to the server over HTTP. No intermediate cloud services, no third-party dependencies — just HealthKit to your server.

What it syncs

• 85+ quantity types — steps, heart rate, blood pressure, blood glucose, body temperature, VO2 max, nutrition, audio exposure, and more
• 22 category types — sleep analysis, menstrual cycles, symptoms, mindfulness, heart events, stand hours
• Workouts — activity type, duration, energy burned, distance, swim strokes, flights climbed
• Blood pressure — systolic/diastolic correlation pairs
• ECG recordings — classification, heart rate, voltage measurements
• Audiograms — hearing sensitivity by frequency
• Workout routes — GPS coordinates recorded during workouts
• Activity summaries — daily ring data (active energy, exercise minutes, stand hours)

Features

• Full and incremental sync — initial backfill of all historical data, then ongoing incremental syncs
• Real-time background sync — HealthKit observer queries for immediate delivery when new data is recorded
• Background processing — periodic sync via BGProcessingTask when the app isn't active
• Live Activity — sync progress on the lock screen and Dynamic Island
• CSV import — import Alpha Progression CSV files via share sheet or file picker
• No dependencies — pure Swift using only Apple frameworks

Requirements

• iOS 16.2+
• Physical device (HealthKit is not available in the Simulator)
• A running FreeReps server accessible from the device's network

Prerequisites

• Tailscale — FreeReps uses Tailscale for authentication and TLS natively (via tsnet). There are no passwords or API keys — access is controlled by your tailnet. Tailscale must be set up before running FreeReps.
• Health Auto Export (iOS, optional) — An alternative way to get Apple Health data into FreeReps via .hae file exports uploaded with freereps-upload. Not needed if using the FreeReps companion app.
• mcp-proxy (optional) — Required for connecting Claude Desktop to a remote FreeReps instance. Bridges stdio↔SSE transports. Install with brew install mcp-proxy or pip install mcp-proxy.

Quick Start

Server (Docker Compose)

git clone https://github.com/meltforce/FreeReps.git
cd FreeReps/server
cp config.example.yaml config.yaml
# Edit config.yaml — set database password, enable Tailscale
docker compose up -d

To use the pre-built image from Docker Hub instead of building locally, replace the app service's build: . with image: meltforce/freereps:latest in docker-compose.yml.

Test Server (Demo Mode)

Run a FreeReps server with demo data (e.g., for App Store review or sync testing):

Using Docker (recommended)

cd FreeReps/server
cp config.example.yaml config.yaml
# Set tailscale.enabled: false in config.yaml for local dev

docker compose up -d db
docker compose run --rm -e FREEREPS_DEMO=true app

From source

cd FreeReps/server
cp config.example.yaml config.yaml
# Set tailscale.enabled: false in config.yaml for local dev

docker compose up -d db
cd web && npm ci && npm run build && cd ..
go run ./cmd/freereps -config config.yaml -demo

This seeds the database with 90 days of realistic health data including heart rate, sleep, workouts, and activity rings. The data is deterministic and idempotent — restarting with -demo or FREEREPS_DEMO=true won't create duplicates.

The server will be available at http://localhost:8080. To tear down:

docker compose down -v

iOS App

1. Open app/FreeReps.xcodeproj in Xcode
2. Set your development team and bundle identifier in Signing & Capabilities
3. Build and run on a physical device
4. In Settings, enter your FreeReps server URL
5. Grant HealthKit permissions and start syncing

Upload Tool (macOS)

freereps-upload is a client-side CLI tool that reads .hae files from your iCloud Drive (exported by Health Auto Export), converts them to REST API format, and uploads them to your FreeReps server over Tailscale.

Install:

curl -sSL https://raw.githubusercontent.com/meltforce/FreeReps/main/server/scripts/install-upload.sh | bash

Usage:

# First run — upload all historical data
freereps-upload \
  -server https://freereps.your-tailnet.ts.net \
  -path ~/Library/Mobile\ Documents/com~apple~CloudDocs/Health\ Auto\ Export/AutoSync

# Subsequent runs — only new/changed files are uploaded (resumable)
freereps-upload \
  -server https://freereps.your-tailnet.ts.net \
  -path ~/Library/Mobile\ Documents/com~apple~CloudDocs/Health\ Auto\ Export/AutoSync

Flags:

| Flag | Default | Description | |------|---------|-------------| | -server | (required) | FreeReps server URL | | -path | (required) | Path to AutoSync directory (or parent) | | -dry-run | false | Parse and convert without sending | | -batch-size | 2000 | Data points per metric payload | | -version | | Print version and exit |

Requirements: lzfse must be installed (brew install lzfse).

Update / Uninstall:

# Update to latest version
curl -sSL https://raw.githubusercontent.com/meltforce/FreeReps/main/server/scripts/install-upload.sh | bash -s -- --update

# Uninstall
curl -sSL https://raw.githubusercontent.com/meltforce/FreeReps/main/server/scripts/install-upload.sh | bash -s -- --uninstall

State tracking: Upload progress is tracked in ~/.freereps-upload/state.db (SQLite). Files are identified by path + size + SHA-256 hash, so changed files are re-uploaded and the tool is fully resumable.

Data Sources

FreeReps iOS App (recommended)

The companion app syncs HealthKit data directly to the server via HTTP POST. Supports full historical backfill and real-time incremental sync.

Oura Ring

FreeReps integrates directly with the Oura API v2 to pull ring data. Syncs every 30 minutes with 90-day initial backfill.

Data synced:

• Oura-exclusive — readiness score, sleep score, activity score, temperature deviation, stress, recovery, resilience, cardiovascular age
• Overlapping with Apple Watch — heart rate, HRV, SpO2, respiratory rate, steps, active calories, workouts, sleep sessions/stages

Source priority dedup: When both Oura and Apple Watch report the same metric, FreeReps deduplicates at query time using configurable source priority (Settings > Source Priority). Only the highest-priority source's data is shown — no double-counting.

Oura Setup

1. Register an Oura API app at cloud.ouraring.com/oauth/applications:

• Redirect URI: https://your-freereps-host.ts.net/oura/callback
• Privacy Policy URL: your FreeReps website's privacy page
• Terms of Service URL: your FreeReps website's terms page
• Enable all scopes

1. Enter credentials in FreeReps: Go to Settings > Oura Ring, enter your Client ID and Client Secret, click "Save Credentials"

1. Authorize: Click "Authorize with Oura", approve access on Oura's page. You'll be redirected back to FreeReps.

1. Sync starts automatically every 30 minutes. Use "Sync Now" for immediate sync. Check Settings > Import Logs for sync status.

Health Auto Export (iOS, legacy)

The iOS app Health Auto Export can export Apple Health data as .hae files to iCloud Drive, which can then be uploaded to FreeReps using the freereps-upload CLI tool.

Alpha Progression (iOS)

Alpha Progression CSV exports provide detailed strength training data (exercises, sets, reps, weight, RIR).

Upload via the dashboard, the iOS companion app (share sheet / file picker), or POST to /api/v1/ingest/alpha.

Dashboard Features

• Daily Overview — Key metrics at a glance (sleep, HRV, RHR, activity)
• Correlation Explorer — Plot any metric against any other (scatter + overlay, Pearson r)
• Sleep View — Hypnogram, stages, HR/HRV/SpO2 during sleep
• Workout View — HR zones, route map, Alpha Progression sets
• Metrics Deep Dive — Time-series with moving average, normal range band
• Saved Views — Store correlation configurations for quick recall

MCP Server

FreeReps exposes health data to Claude (and other LLMs) via the Model Context Protocol.

Tools: get_health_metrics, get_workouts, get_sleep_data, get_metric_stats, get_correlation, compare_periods, list_available_metrics, get_workout_sets

Resources: daily_summary, recent_workouts, metric_catalog

stdio (Claude Code)

freereps --mcp -config config.yaml

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "freereps": {
      "command": "/path/to/freereps",
      "args": ["--mcp", "-config", "/path/to/config.yaml"]
    }
  }
}

SSE (Remote via mcp-proxy)

The MCP SSE endpoint is available at /mcp/sse when the server is running. To connect Claude Desktop (or other stdio-only clients) to a remote FreeReps instance, use mcp-proxy to bridge stdio↔SSE:

brew install mcp-proxy   # or: pip install mcp-proxy

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "freereps": {
      "command": "mcp-proxy",
      "args": ["https://freereps.your-tailnet.ts.net/mcp/sse"]
    }
  }
}

No local FreeReps binary needed — mcp-proxy handles the transport bridging, and Tailscale handles authentication.

Supported Metrics

| Category | Metrics | |----------|---------| | Cardiovascular | heartrate, restingheartrate, heartratevariability, bloodoxygensaturation, respiratoryrate, vo2max | | Sleep | sleepanalysis, applesleepingwristtemperature | | Body | weightbodymass, bodyfatpercentage | | Activity | activeenergy, basalenergyburned, stepcount, flightsclimbed, appleexercisetime | | Oura | readinessscore, sleepscore, activityscore, temperaturedeviation, stress, recovery, resilience, cardiovascular_age | | Workouts | All types (with HR data + routes, deduped across sources) |

Design Principles

• Privacy first — All data stays local. No cloud uploads, no telemetry.
• Self-hosted — Runs on your own server/homelab.
• Data over scores — Raw data + visualization + LLM instead of proprietary algorithms.
• Flexible over opinionated — Correlation explorer instead of hard-wired dashboards.
• Single binary — Go binary with embedded web UI.

API Reference

| Endpoint | Method | Description | |----------|--------|-------------| | /api/v1/ingest/ | POST | Ingest health data JSON | | /api/v1/ingest/alpha | POST | Ingest Alpha Progression CSV | | /api/v1/ingest/import | POST | Unified import (auto-detects format) | | /api/v1/metrics/latest | GET | Latest value per metric | | /api/v1/metrics | GET | Time-range metric query | | /api/v1/metrics/stats | GET | Metric statistics (avg, min, max, stddev) | | /api/v1/timeseries | GET | Time-bucketed metric data | | /api/v1/correlation | GET | Pearson r between two metrics | | /api/v1/sleep | GET | Sleep sessions + stages | | /api/v1/workouts | GET | Workout list with filters | | /api/v1/workouts/{id} | GET | Workout detail | | /api/v1/workouts/{id}/sets | GET | Alpha Progression sets | | /api/v1/allowlist | GET | Metric allowlist | | /api/v1/metrics/available | GET | Available metrics with display metadata | | /api/v1/metrics/visibility | PUT | Save per-user metric visibility | | /api/v1/source-priority | GET/PUT | Source priority configuration | | /api/v1/oura/status | GET | Oura connection status | | /api/v1/oura/credentials | PUT | Save Oura OAuth2 credentials | | /api/v1/oura/authorize | POST | Start Oura OAuth2 flow | | /api/v1/oura/sync | POST | Trigger manual Oura sync | | /api/v1/oura/disconnect | DELETE | Remove Oura connection | | /api/v1/me | GET | Current user identity |

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: meltforce
• Source: meltforce/FreeReps
• License: MIT
• Homepage: https://freereps.meltforce.org/

Install and usage instructions live in the source repository linked above.