livetrack-mcp
Autonomous MCP server that polls Garmin LiveTrack, stores time-series in SQLite, and triggers Claude analysis every 10 minutes via claude-runner.
Architecture
Garmin LiveTrack URL
│
│ (poll every 60 s)
▼
livetrack-mcp (port 38100)
├── poller.py — fetch trackpoints from Garmin API
├── store.py — SQLite time-series persistence (/data/livetrack.db)
├── tracker.py — asyncio scheduling + race-end detection
└── analyzer.py — build prompt, call claude-runner
│
│ POST /run (fire-and-forget)
▼
claude-runner (port 38095)
│
│ claude -p <analysis prompt>
▼
Claude (sonnet)
├── analyze timeseries
├── curl POST /control if thresholds need adjustment
└── mcp__telegram__send_message → coaching push
Key design: livetrack-mcp is fully autonomous — no Claude session needs to stay alive during the race. Claude is called as a stateless analysis function every 10 minutes. If claude-runner is temporarily unavailable, the next analysis cycle retries automatically.
MCP Tools
| Tool | Description |
|---|---|
start_tracking(url, race_config) | Start polling a LiveTrack share URL |
stop_tracking() | Stop polling (also auto-stops at race end) |
get_tracking_status() | Active state, elapsed time, stale time, poll errors |
get_timeseries(minutes=10) | Recent data from SQLite |
update_thresholds(updates) | Update HR/power thresholds mid-race |
trigger_analysis() | Manual on-demand analysis, bypassing schedule |
Custom HTTP Endpoints
| Endpoint | Method | Description |
|---|---|---|
/control | POST | Update thresholds mid-race (called by Claude via curl in Bash tool) |
/health | GET | Health check — tracking state + store stats |
/control usage (from Claude's analysis prompt)
curl -sf -X POST http://localhost:38100/control \
-H 'Content-Type: application/json' \
-d '{"power_max": 150}'
Allowed fields: hr_max, hr_min, power_max, power_min, cadence_min, run_hr_max, run_hr_min, run_cadence_min
race_config Fields
| Field | Type | Default | Description |
|---|---|---|---|
hr_max | int | — | Cycling HR ceiling (bpm) |
hr_min | int | — | Cycling HR floor |
power_max | int | — | ERG power ceiling (watts) |
power_min | int | — | ERG power floor |
cadence_min | int | — | Minimum cycling cadence (rpm) |
run_hr_max | int | — | Run HR ceiling |
run_hr_min | int | — | Run HR floor |
run_cadence_min | int | — | Minimum run cadence (spm) |
poll_interval_secs | int | 60 | How often to poll LiveTrack |
analyze_interval_secs | int | 600 | How often to trigger Claude analysis |
analyze_window_min | int | 10 | Data window passed to Claude (minutes) |
Example race_config for a full triathlon
{
"race_name": "CT2026",
"race_type": "triathlon",
"hr_max": 144,
"hr_min": 115,
"power_max": 165,
"cadence_min": 82,
"run_hr_max": 152,
"run_hr_min": 125,
"run_cadence_min": 165,
"poll_interval_secs": 60,
"analyze_interval_secs": 600,
"analyze_window_min": 10
}
Race-End Detection
The server auto-stops when:
- No new trackpoints for ≥ 15 minutes (
STALE_STOP_MIN) - AND total elapsed time ≥ 30 minutes (
MIN_ELAPSED_MIN)
This handles the Garmin 24-hour URL delay: the URL remains valid after the race, but new trackpoints stop arriving when the athlete finishes. The 30-minute minimum prevents false stops at the start when GPS data is sparse.
Configuration (Environment Variables)
| Variable | Default | Description |
|---|---|---|
PORT | 38100 | Server port |
HOST | 0.0.0.0 | Bind address |
MCP_PATH | /mcp | MCP endpoint path |
DB_PATH | /data/livetrack.db | SQLite database path |
CLAUDE_RUNNER_URL | http://localhost:38095 | claude-runner base URL |
RUNNER_WORKSPACE | training | Workspace for claude-runner tasks |
LOG_LEVEL | INFO | Logging level |
OTEL_EXPORTER_OTLP_ENDPOINT | — | OpenTelemetry collector URL (optional) |
Deployment
cd ~/ai-platform/mcps
# Build and start
docker compose up -d --build livetrack-mcp
# Logs
docker compose logs -f livetrack-mcp
# Restart
docker compose restart livetrack-mcp
# Health check
curl http://localhost:38100/health
Typical Session (via Claude in training workspace)
# Start tracking
use_mcp_tool livetrack-mcp start_tracking \
url="https://livetrack.garmin.com/session/.../token/..." \
race_config={"hr_max": 144, "power_max": 165, "run_hr_max": 152}
# Check status
use_mcp_tool livetrack-mcp get_tracking_status
# Manual analysis trigger
use_mcp_tool livetrack-mcp trigger_analysis
# Stop (or let it auto-stop)
use_mcp_tool livetrack-mcp stop_tracking
Project Structure
livetrack_mcp/
├── Dockerfile
├── pyproject.toml
├── README.md
└── src/livetrack_mcp/
├── __init__.py
├── __main__.py
├── otel.py # OpenTelemetry setup
├── poller.py # Garmin LiveTrack URL parsing + HTTP fetch
├── store.py # SQLite time-series (sqlite3 + asyncio.to_thread)
├── tracker.py # Scheduling (asyncio.create_task) + race-end detection
├── analyzer.py # Prompt builder + claude-runner caller
└── server.py # FastMCP tools + /control + /health