TrainBud

TrainBud

Talk to your training data.

TrainBud is an open-source MCP server that connects your Garmin Connect fitness data to Claude, Cursor, and other AI assistants. Ask about workouts, sleep, heart rate, recovery, and body composition in plain English — privately, on your machine.

Disclaimer: TrainBud is an unofficial community project. It is not affiliated with, endorsed by, or sponsored by Garmin Ltd. Garmin Connect is a trademark of Garmin Ltd.

Try it

Once connected to your MCP client, ask things like:

• *"What did I do today?"*
• *"How's my sleep been this week?"*
• *"Am I recovered enough to train hard tomorrow?"*
• *"Is my resting heart rate trending down?"*

See examples/prompts.md for more ideas.

Why TrainBud

• Private — credentials stay in your local .env; data is cached on your machine
• Local-first — SQLite cache, session tokens in .trainbud/
• Works everywhere — Windows, macOS, Linux (Node.js 22.12+)
• Any MCP client — Claude Desktop, Cursor, and other stdio-compatible clients
• Smart fetching — batched API calls and automatic re-auth when sessions expire

Quick start

npx trainbud setup

The setup wizard walks you through credentials, authentication, and connecting Cursor or Claude Desktop — no MCP config editing required. Then restart your MCP client and ask it what you did today.

To keep trainbud on your PATH instead of typing npx every time:

npm install -g trainbud

trainbud setup

Needs Node 22.12+. Full walkthrough: QUICKSTART.md

From source (for contributors, or to run an unreleased commit)

git clone https://github.com/Zsadigzade/trainbud.git

cd trainbud npm install npm run build npm link # puts trainbud on your PATH; undo with npm unlink -g trainbud trainbud setup

Without npm link, every trainbud in this README is node dist/index.js run from the repo root. If dist/ does not exist yet, run npm run build first.

Claude Code plugin (recommended)

Install as a Claude Code plugin — skills and MCP server in one step:

/plugin marketplace add Zsadigzade/trainbud

/plugin install trainbud@trainbud

Set credentials, then restart Claude Code:

export GARMIN_EMAIL="your@email.com"

export GARMIN_PASSWORD="yourpassword"

Plugin files live in plugin/. See plugin/README.md.

Claude Code skills (in-repo)

This repo also ships project skills in .claude/skills/ for development without installing the plugin:

Open the repo in Claude Code (claude in this directory) — skills load automatically.

To use skills in every project without the plugin, copy them to ~/.claude/skills/.

After setup, restart your MCP client and try /trainbud with *"What did I do today?"*

Dashboard

trainbud serve hosts a dashboard at /dashboard. It is phone-first, because the pairing flow is: you are standing next to the watch holding a phone when you approve a code.

It shows what stands out today against your own baselines, this week against last week, and resting heart rate and sleep plotted against your own 30-day median — all read from the local history store, so it paints instantly and works even when your Connect session has expired. A break in a line is a day with no measurement, not a zero.

It is also where you tell TrainBud who it is talking to:

Usage. TrainBud runs on your own AI provider key, so every question and every daily insight is charged to you. The dashboard shows the tokens and cost per call, the month to date, and a 30-day chart. A model this build has no published price for is recorded with its cost left *unknown* rather than as zero — a call priced at zero would make a cap that can never trip.

Nothing on this page leaves your machine. There is no endpoint to send it to.

Garmin watch widget (Connect IQ)

View recovery, sleep, activity, stress, and VO2 max on your Garmin watch via a Connect IQ widget in ciq/.

Requires: trainbud serve running + HTTPS tunnel (same setup as web AI).

1. Start the server and tunnel:

   trainbud serve

cloudflared tunnel --url http://127.0.0.1:3847

2. Build and sideload the widget — see [ciq/README.md](./ciq/README.md)

1. In Garmin Connect Mobile → Connect IQ → TrainBud settings, set:

• Server URL — your tunnel URL (e.g. https://abc.trycloudflare.com)

1. Open the widget on your watch — it shows a pairing code. Approve it in the dashboard (/dashboard?token=YOUR_API_KEY) to complete setup. The dashboard swaps that token for a session cookie and drops it from the URL, so the address bar is safe to screenshot afterwards.

The glance shows recovery and sleep, or the top finding in a few characters ("RHR +4 bpm"), from the last cached summary, so it renders without waiting on the network; once that is more than two hours old it says so. Open it and tap or swipe to cycle through the cards you left switched on in the dashboard. The watch calls GET /api/watch — a compact JSON summary, not the full MCP protocol.

On the Today card, START (or tap) opens a finding to the rule it fired on — "Each of the last 3 days was at least 3 bpm and 2 deviations above your 28-day median of 48 bpm" — and from there it can be muted for three days (POST /api/mute). The Sleep card names what moved last night against your own nights ("Deep 40m (1h24m)"). On the Forerunner 55, whose widget has 64 KB, those two are compiled out so the rest still fits.

Detector rules

Every finding fires on a rule you can see and move. The dashboard's Detector rules section holds the bars — resting HR days/bpm/deviations, sleep-debt hours, HRV drop, the training-load ratios, and "several signals together" (resting HR up, HRV down and sleep stress up at once) — bounded so no setting makes every day, or no day, a finding. Every surface shows the rule a finding fired on, with the numbers that were in force.

Voice (/voice)

Hold a button on your phone, ask a question out loud, hear the answer read back. Open https://YOUR-HOST/voice?token=YOUR_API_KEY once; it trades the key for a cookie and redirects to a clean URL.

• Android / Chrome — speech recognition happens in the browser. Free, no key.
• iPhone / Safari — records audio and transcribes it server-side via Groq (whisper-large-v3-turbo, about $0.04 per hour of audio). Add the key on the dashboard.
• Both — answers are spoken back, and Read me my day / Read today's insight cost nothing at all: they are composed in code from data already on hand, not generated.

Not a watch feature and it cannot be one: Connect IQ exposes no microphone or speaker to a widget. Not hands-free either — mobile browsers suspend the microphone when the tab is backgrounded, so the phone has to be awake with the page in front of you.

Full detail: docs/VOICE.md

Always on (/voice and the watch, without babysitting a terminal)

trainbud serve in a terminal lasts until the terminal closes. To have the server and the tunnel come back by themselves after a reboot:

.\scripts\install-always-on.ps1 -Hostname trainbud.example.com

That registers a scheduled task for the server and a watchdog that checks both halves every five minutes — because a tunnel that answers is not a server that answers: a tunnel with nothing behind it serves its own error page under a 200, so the link looks alive while the watch reports HTTP -400. systemd, launchd and Docker Compose recipes are in the guide.

Full detail, including Cloudflare named tunnels: docs/ALWAYS-ON.md

Connect to Claude Desktop

Edit claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{

"mcpServers": { "trainbud": { "command": "node", "args": ["C:/path/to/trainbud/dist/index.js", "start"], "env": { "GARMIN_EMAIL": "your@email.com", "GARMIN_PASSWORD": "yourpassword" } } } }

With trainbud on your PATH (npm install -g trainbud, or npm link from a clone), point the client at the command instead of a path:

{

"mcpServers": { "trainbud": { "command": "trainbud", "args": ["start"] } } }

Restart your MCP client, then start asking questions.

Tools

CLI

trainbud setup          # Interactive first-time setup (recommended)

trainbud serve # Remote HTTP