SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformstrainbud

trainbud

Local analysis of Garmin Connect activities, sleep, recovery, body composition, stress and VO2 max against 28-day baselines, with memory for goals and races.

Open website

About this tool

TrainBud is an open-source MCP (Model Context Protocol) server designed to connect Garmin Connect fitness data to Claude, Cursor, and other MCP-compatible AI assistants. Users can ask about training, sleep, heart rate, recovery, and body composition in natural language, with all data processed on the local machine and credentials stored only in a local .env file.

Purpose

TrainBud lets users query their own Garmin training data conversationally through an AI assistant. After connecting an MCP client, you can ask questions such as "What did I do today?", "How was my sleep this week?", "Have I recovered enough for high-intensity training tomorrow?", and "Is my resting heart rate trending downward?"

Key Capabilities

  • Local-first: Uses a SQLite cache, with session tokens stored in the .trainbud/ directory and data cached on the local machine.
  • Cross-platform: Supports Windows, macOS, and Linux, and requires Node.js 22.12+.
  • Compatible with any MCP client: Such as Claude Desktop, Cursor, and other stdio-compatible clients.
  • Smart fetching: Batched API calls, with automatic re-authentication when the session expires.
  • Dashboard: trainbud serve provides a mobile-first dashboard at /dashboard, showing the day's highlights, this week versus last week comparisons, resting heart rate, and sleep compared with the 30-day median, with data coming from local history storage so it displays instantly even if the Connect session has expired.
  • Usage monitoring: The dashboard shows tokens and cost per call, monthly totals, and a 30-day chart.
  • Garmin watch widget (Connect IQ): View recovery, sleep, activity, stress, and VO2 max on a Garmin watch via the Connect IQ widget in ciq/. Requires trainbud serve running together with an HTTPS tunnel.
  • Voice interaction (/voice): Hold a button on your phone to ask a question and get a spoken answer. Android/Chrome uses browser speech recognition (free); iPhone/Safari uses Groq server-side transcription (whisper-large-v3-turbo, about $0.04/hour of audio).
  • Always on: Scheduled tasks and a watchdog can be registered so the server and tunnel automatically recover after a restart.
  • Docker support: A published image ghcr.io/zsadigzade/trainbud is provided, and you can also build it yourself.

How to Use

  1. Installation: Requires Node 22.12+. You can run it directly with npx trainbud <command>, install it globally with npm install -g trainbud, or run npm link after cloning the repository.
  2. Setup wizard: Guides you through credentials, authentication, and connecting Cursor or Claude Desktop, with no need to manually edit the MCP configuration.
  3. Connect Claude Desktop: Edit claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json; macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), and point the client to the trainbud command.
  4. Claude Code plugin: Can be installed as a Claude Code plugin, including the skill and MCP server in one step.
  5. Dashboard: After running trainbud serve, visit /dashboard, and first obtain a session cookie via /dashboard?token=YOUR_API_KEY.
  6. Watch widget: Start the server and tunnel (trainbud serve cloudflared tunnel --url http://127.0.0.1:3847），构建并侧载小部件，在 Set the server URL in Garmin Connect Mobile, then open the widget on the watch to get a pairing code and approve it in the dashboard.
  7. Voice: Open https://YOUR-HOST/voice?token=YOUR_API_KEY Once, after exchanging for a cookie, redirect to a clean URL.
  8. Docker: Mount a volume to /app/.trainbud to preserve SQLite history, cached sessions, and logs. Use the -i flag when running as an MCP server; set TRAINBUD_HOST=0.0.0.0 when running as an HTTP server.

Use Cases

  • Fitness enthusiasts who want to query their personal Garmin training data in natural language.
  • Users who need to integrate Garmin data into AI assistant workflows.
  • Fitness-minded people who focus on metrics such as recovery, sleep, and heart rate variability.
  • Runners or cyclists who want to quickly view key metrics on their Garmin watch.

Limitations

  • Unofficial project: Not affiliated with Garmin Ltd., uses the unofficial garmin-connect npm package, and Garmin may change the API at any time.
  • MFA not supported: The underlying library does not support multi-factor authentication; MFA must be disabled or an app-specific password must be used.
  • AI features require your own key: AI features run on the user's own Anthropic key, and costs are borne by the user.
  • Not a hosted service: There is no TrainBud account or server; you need to run it locally yourself.
  • Voice is not a watch feature: Connect IQ does not expose a microphone or speaker to widgets; mobile browsers pause the microphone when the tab is in the background.
  • Security note: The session token .trainbud/session.json is as sensitive as a password; the server binds to 127.0.0.1 by default and should only be accessible from the internet when pointed at a tunnel.
  • License: MIT.

Related tools

Browse category