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.
Once connected to your MCP client, ask things like:
See examples/prompts.md for more ideas.
.env; data is cached on your machine.trainbud/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+. Full walkthrough: QUICKSTART.md
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 <command> in this README is
node dist/index.js <command> run from the repo root. If dist/ does not exist yet,
run npm run build first.
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"
| Command | What it does |
|---|---|
/trainbud:trainbud-setup | First-time setup and diagnostics |
/trainbud:trainbud | Ask about workouts, sleep, recovery, HR, stress, VO2 max |
Plugin files live in plugin/. See plugin/README.md.
This repo also ships project skills in .claude/skills/ for development without installing the plugin:
| Command | What it does |
|---|---|
/trainbud-setup | Install, authenticate, configure MCP, run live check |
/trainbud | Ask about workouts, sleep, recovery, HR, stress, VO2 max |
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?"
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:
| Setting | What it changes |
|---|---|
| Name, units, primary sport, weekly goal | Every renderer, and what the AI is told about you |
| Thresholds | Where green becomes amber and amber becomes red — on the watch too |
| Watch cards | Which cards appear on the wrist and in what order, live on the next sync |
| AI model, tone, answer length | How the Ask card and the daily insight sound |
| Your own Ask questions | Up to five, 32 characters each. They lead the watch's Ask menu; the rest of the slots stay generated from what fired |
| Monthly spending cap | Optional. Refuses an Ask past the cap instead of spending past it |
| Privacy | Local feature counters, on by default, with a delete button |
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.
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).
trainbud serve
cloudflared tunnel --url http://127.0.0.1:3847
https://abc.trycloudflare.com)/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 from the last cached summary, so it renders without
waiting on the network. 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.
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.
| Tool | What it answers |
|---|---|
get_latest_activity | Your most recent workout — distance, pace, HR, elevation |
get_activities_range | Activities between two dates |
get_sleep_data | Sleep duration, stages, score, awakenings |
get_heart_rate_trends | Resting, max, and average HR over time |
get_recovery_status | Recovery score from HRV, sleep, stress, resting HR |
get_body_composition | Weight, body fat, and muscle mass trends |
get_stress_levels | Daily stress averages and trends |
get_vo2_max_trends | VO2 max fitness trends over time |
get_training_insights | Combined weekly summary (activities, sleep, recovery, stress) |
get_findings | What stands out against your own 28-day baselines, not a population average |
get_week_review | This week against last, the load forecast, sleep debt, and your next race |
compare_workouts | One workout against your own earlier efforts of the same type and distance |
remember_context | Record a goal, a race and its date, an injury, or a note |
get_user_context | What is on record about you, on any date |
log_subjective | How a session actually felt — RPE, soreness, mood |
trainbud setup # Interactive first-time setup (recommended)
trainbud serve # Remote HTTP MCP for web AI (claude.ai, ChatGPT)
trainbud check # Live diagnostics against all tools
trainbud doctor # What the watch would see: public URL, AI key, history depth
trainbud backfill # Pull Garmin history into the local store (resumable)
trainbud findings # What stands out against your own baselines
trainbud start # Start the MCP server (stdio)
trainbud auth # Force re-authentication
trainbud cache clear # Clear cached data
trainbud devices # List paired watches
trainbud devices revoke <id> # Take one watch's access away
trainbud status # Show session and cache status
trainbud --version # Print version
Every one of these also works as npx trainbud <command> without installing anything.
trainbud: command not foundEither use npx trainbud <command>, or install it globally with
npm install -g trainbud. Running from a clone instead? Run npm link once from the
repo root, or call the built entry point directly with node dist/index.js doctor
(after npm run build).
| Variable | Default | Description |
|---|---|---|
GARMIN_EMAIL | — | Garmin Connect email |
GARMIN_PASSWORD | — | Garmin Connect password |
TRAINBUD_SESSION_PATH | .trainbud/session.json | Session token storage |
TRAINBUD_LOG_PATH | .trainbud/mcp.log | Log file path |
TRAINBUD_CACHE_PATH | .trainbud/cache.db | SQLite cache database |
CACHE_TTL_ACTIVITIES | 1800 | Activity cache TTL (seconds) |
CACHE_TTL_SLEEP | 7200 | Sleep cache TTL (seconds) |
CACHE_TTL_STATS | 3600 | Stats cache TTL (seconds) |
TRAINBUD_API_KEY | auto-generated | Bearer token for HTTP MCP (trainbud serve) |
TRAINBUD_HOST | 127.0.0.1 | Bind host for HTTP server |
TRAINBUD_PORT | 3847 | Bind port for HTTP server |
.env file — never sent to a third party.trainbud/session.json are as sensitive as a passwordgarmin-connect npm package (not Garmin's enterprise OAuth API)127.0.0.1 by default. It is only reachable from the internet if
you point a tunnel at it, and every route except /health needs the API key/dashboard?token=…, then trades it for an
HttpOnly session cookie and redirects to a clean URL — so the key does not sit in
your address bar, your history, or a screenshottrainbud devices lists them, trainbud devices revoke <id> takes one away — without logging out the dashboard, /mcp, or your
other watches. A watch paired before 0.5.2 holds the API key itself; re-pair it to
swap that for a scoped tokenContent-Security-Policy, X-Content-Type-Options,
X-Frame-Options and Referrer-Policy, including the 401s. HSTS is sent only on a
request that actually arrived over TLS, so the loopback dashboard stays reachable| Issue | Fix |
|---|---|
| Authentication failed | Verify .env credentials, run trainbud auth |
| MFA enabled on account | Disable MFA or use an app-specific password |
| Stale data | Run trainbud cache clear |
| Rate limited | Wait 60 seconds; cached responses are used when available |
| Watch shows "Not a TrainBud server" or error -400 | Your public URL is answering with something that is not TrainBud's JSON — usually a tunnel that is down. Run trainbud doctor; it says exactly what came back |
| Watch shows "Watch not authorised" | The API key changed since the watch paired. Pair it again from the dashboard |
| Watch shows "AI not set up" | AI is bring-your-own-key. Paste an Anthropic key into the dashboard |
| No sleep/HR data | Ensure your Garmin device has synced to Garmin Connect |
| Server won't start | Check that GARMIN_EMAIL and GARMIN_PASSWORD are set in .env |
A published image, built and exercised in CI on every push so it is not a promise that quietly rots:
docker pull ghcr.io/zsadigzade/trainbud:latest
Or build it yourself from this repository:
docker build -t trainbud .
One thing matters more than the rest: mount a volume at /app/.trainbud.
That is where the SQLite history, the cached session and the log live. Without
it, every container restart throws away your downloaded history and
re-authenticates from scratch.
The default entrypoint speaks MCP over stdio, so the client runs the container:
{
"mcpServers": {
"trainbud": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "GARMIN_EMAIL", "-e", "GARMIN_PASSWORD",
"-v", "trainbud-data:/app/.trainbud",
"trainbud"
]
}
}
}
-i is required — without it the container has no stdin and the client sees a
server that connects and immediately goes quiet. The two -e flags with no
value pass the variables through from your own environment, so your credentials
stay out of the config file.
docker run --rm -p 3847:3847 \
-e GARMIN_EMAIL -e GARMIN_PASSWORD \
-e TRAINBUD_API_KEY \
-e TRAINBUD_HOST=0.0.0.0 \
-v trainbud-data:/app/.trainbud \
--entrypoint node trainbud dist/index.js serve
TRAINBUD_HOST=0.0.0.0 is needed inside a container: the server binds
127.0.0.1 by default, which is the right default on a laptop and unreachable
from outside a container.
trainbud setup is interactive and assumes a terminal, so with Docker do the
one-off backfill directly:
docker run --rm -e GARMIN_EMAIL -e GARMIN_PASSWORD \
-v trainbud-data:/app/.trainbud \
--entrypoint node trainbud dist/index.js backfill
The same pattern runs doctor, check and devices.
npm install
npm run build
npm test # the whole suite, via the Node test runner
npm run lint
npm run dev # Start with auto-reload
Use .nvmrc with nvm/fnm for Node 22. npm run test:coverage reports coverage through Node's own test runner, and npm run test:watch reruns on change.
See CONTRIBUTING.md and docs/VAULT.md for architecture and design notes (Obsidian vault, outside this repo).
ghcr.io/zsadigzade/trainbudMIT — see LICENSE.
Garmin Connect is a trademark of Garmin Ltd. This project is not affiliated with Garmin Ltd.
FAQs
TrainBud — talk to your Connect fitness data through Claude and other MCP clients
The npm package trainbud receives a total of 253 weekly downloads. As such, trainbud popularity was classified as not popular.
We found that trainbud demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
The compromise affects MemTensor's MemOS, an open source memory framework for large language models (LLMs) and AI agents. Both npm package @memtensor/memos-cloud-openclaw-plugin and the PyPI package MemoryOS are compromised. They drop cross-platform Go binaries that exfiltrate developer secrets.
Security News
Lovable’s OJ rewrites Vite’s dev server in Rust, reducing memory use and preview times as AI lowers the cost of open source reimplementation.
Security News
It has been one year since Shai-Hulud made its first appearance on npm.