TrainBud

MCP办公协作

提供方 未标注

办公协作 stdio · 本地进程 未标注 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

与您的Garmin Connect训练数据对话。14个工具涵盖活动、睡眠、心率、恢复、身体成分、压力和最大摄氧量,外加一个用于目标和比赛的内存层。发现结果由代码中的检测器根据您自己的28天基线计算得出,而非模型生成。本地运行:凭据保存在本地.env文件中,SQLite缓存存储在您的机器上,无需账户,也无托管服...

一句话选型结论

按资料字段整理

TrainBud 属于办公协作类 MCP 服务器,stdio · 本地进程,鉴权方式未标注,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类办公协作 传输方式stdio · 本地进程 鉴权未标注 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

办公协作
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

生产力

安装与配置

stdio · 本地进程 未标注
客户端在本机拉起子进程,数据不出本机
npx trainbud setup

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
日程与消息

查日程、发消息、约会议。

表单与审批

填表单、走审批流。

团队协作

同步任务、汇总进展。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在办公协作场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
TrainBud当前 未标注 stdio · 本地进程 本地部署 有 未标注
CowAgent 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Karakeep MCP 未标注 未标注 未标注 无 2026-05-17
agentscope 未标注 stdio · 本地进程 本地部署 有 2026-04-11
note-gen 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Everywhere 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

办公协作
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类办公协作本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式未标注远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

18.6 KB
来自项目仓库与上游目录的原文,未做删改

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```bash

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:```bash
npm install -g trainbud
trainbud setup

Needs Node 22.12+. Full walkthrough: QUICKSTART.md

From source (for contributors, or to run an unreleased commit)``bash git clone https://github.com/Zsadigzade/trainbud.git cd trainbud npm install npm run build npm link # putstrainbudon your PATH; undo withnpm 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:```bash
/plugin marketplace add Zsadigzade/trainbud
/plugin install trainbud@trainbud

Set credentials, then restart Claude Code:```bash
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`.

## Claude Code skills (in-repo)

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?"*

## 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:

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

## 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:```bash
   trainbud serve
   cloudflared tunnel --url http://127.0.0.1:3847
   ```
2. Build and sideload the widget — see ciq/README.md
3. In **Garmin Connect Mobile** → Connect IQ → TrainBud settings, set:
   - **Server URL** — your tunnel URL (e.g. `https://abc.trycloudflare.com`)
4. 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:```powershell
.\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````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:```json
{
  "mcpServers": {
    "trainbud": {
      "command": "trainbud",
      "args": ["start"]
    }
  }
}

Restart your MCP client, then start asking questions.

Tools

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 — and which parts of last night were unusual for you
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, with the rule each finding fired on
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

CLI```bash

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, and the rule each fired on
trainbud rederive # Rebuild sleep measurements (deep, REM, awakenings) from the local archive — no Garmin requests
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 rotate status # Which secrets are set, and whether their two homes agree
trainbud rotate api-key # Replace TRAINBUD_API_KEY, and say what that invalidates
trainbud rotate ai-key # Replace the AI key in BOTH .env and app.db
trainbud status # Show session and cache status
trainbud --version # Print version


`rotate ai-key` writes both stores on purpose. The AI key lives in `.env` *and* in
`app.db`, the database copy is the one actually read, and hand-editing only the file
leaves a rotated key that never took effect.

Every one of these also works as `npx trainbud ` without installing anything.

### Troubleshooting: `trainbud: command not found`

Either use `npx trainbud `, 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`).

## Configuration

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

## Security &amp; privacy

- Credentials live only in your local `.env` file — never sent to a third party
- Session tokens in `.trainbud/session.json` are as sensitive as a password
- Tool errors are sanitized before reaching the AI client
- Uses the unofficial `garmin-connect` npm package (not Garmin&#x27;s enterprise OAuth API)
- **MFA is not supported** by the underlying library — disable MFA or use an app-specific password
- The server binds `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
- The dashboard takes the key once, on `/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 screenshot
- **A paired watch holds a token scoped to that watch**, minted at pairing and stored
  on the server as a SHA-256 hash. `trainbud devices` lists them, `trainbud devices
  revoke ` 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 token
- Every response carries `Content-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

### What TrainBud is not

- **Not a hosted service.** There is no TrainBud account and no TrainBud server. You run
  it, on your machine, against your own Garmin credentials
- **Not an official Garmin integration.** It drives an unofficial library against the
  Connect web API. Garmin can change that API without notice, and does
- **Not MFA-compatible.** If your Connect account has MFA on, this will not log in
- **Not free to ask.** The AI features run on your own Anthropic key and are billed to
  you. The dashboard meters every call and can refuse past a cap you set

## Troubleshooting

| 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 &quot;Not a TrainBud server&quot; or error -400 | Your public URL is answering with something that is not TrainBud&#x27;s JSON — usually a tunnel that is down. Run `trainbud doctor`; it says exactly what came back |
| Watch shows &quot;Watch not authorised&quot; | The API key changed since the watch paired. Pair it again from the dashboard |
| Watch shows &quot;AI not set up&quot; | 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&#x27;t start | Check that `GARMIN_EMAIL` and `GARMIN_PASSWORD` are set in `.env` |

## Docker

A published image, built and exercised in CI on every push so it is not a
promise that quietly rots:```bash
docker pull ghcr.io/zsadigzade/trainbud:latest

Or build it yourself from this repository:```bash
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.

### As an MCP server for a desktop client

The default entrypoint speaks MCP over stdio, so the client runs the container:```json
{
  &quot;mcpServers&quot;: {
    &quot;trainbud&quot;: {
      &quot;command&quot;: &quot;docker&quot;,
      &quot;args&quot;: [
        &quot;run&quot;, &quot;-i&quot;, &quot;--rm&quot;,
        &quot;-e&quot;, &quot;GARMIN_EMAIL&quot;, &quot;-e&quot;, &quot;GARMIN_PASSWORD&quot;,
        &quot;-v&quot;, &quot;trainbud-data:/app/.trainbud&quot;,
        &quot;trainbud&quot;
      ]
    }
  }
}

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

As an HTTP server, for the watch app or a web client```bash

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.

### Filling the history

`trainbud setup` is interactive and assumes a terminal, so with Docker do the
one-off backfill directly:```bash
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.

Development```bash

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

Roadmap

  • [x] VO2 max trends
  • [x] Stress levels
  • [x] Training insights
  • [x] Workout comparison
  • [x] Docker image — published to ghcr.io/zsadigzade/trainbud

License

MIT — see LICENSE.

Garmin Connect is a trademark of Garmin Ltd. This project is not affiliated with Garmin Ltd.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
TrainBud 怎么安装?

在客户端按下面的安装命令接入:npx trainbud setup。装完在客户端配置里引用同一个包或端点。

TrainBud 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

TrainBud 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

TrainBud 需要 API Key 吗?

资料没有标注鉴权方式,是否需要密钥取决于服务本身,接入前按官方文档确认。

TrainBud 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

TrainBud 能提供哪些能力?

资料显示能力标签包括 生产力。具体工具清单以官方文档为准。

TrainBud 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

TrainBud 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。