GarminBud

Talk to your Garmin data.

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

• Private — credentials stay in your local .env; data is cached on your machine
• Local-first — SQLite cache, session tokens in .garmin/
• Works everywhere — Windows, macOS, Linux (Node.js 20+)
• 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

git clone https://github.com/Zsadigzade/garmin-bud.git
cd garmin-bud
npm install
npm run build
npx garmin-bud setup

The setup wizard walks you through credentials, authentication, and connecting Cursor or Claude Desktop — no MCP config editing required.

Full walkthrough: QUICKSTART.md

Claude Code plugin (recommended)

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

/plugin marketplace add Zsadigzade/garmin-bud
/plugin install garmin-bud@garmin-bud

Set credentials, then restart Claude Code:

export GARMIN_EMAIL="[email protected]"
export GARMIN_PASSWORD="yourpassword"

| Command | What it does | |---------|----------------| | /garmin-bud:garmin-bud-setup | First-time setup and diagnostics | | /garmin-bud:garmin-bud | 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 | |---------|----------------| | /garmin-bud-setup | Install, authenticate, configure MCP, run live check | | /garmin-bud | 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 /garmin-bud with "What did I do today?"

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: garmin-bud serve running + HTTPS tunnel (same setup as web AI).

1. Start the server and tunnel:

   garmin-bud 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 → GarminBud 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.

Tap the widget to cycle through data cards. The watch calls GET /api/watch — a compact JSON summary, not the full MCP protocol.

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": {
    "garmin-bud": {
      "command": "node",
      "args": ["C:/path/to/garmin-bud/dist/index.js", "start"],
      "env": {
        "GARMIN_EMAIL": "[email protected]",
        "GARMIN_PASSWORD": "yourpassword"
      }
    }
  }
}

After npm link, you can use the CLI directly:

{
  "mcpServers": {
    "garmin-bud": {
      "command": "garmin-bud",
      "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 | | 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) |

CLI

garmin-bud setup          # Interactive first-time setup (recommended)
garmin-bud serve          # Remote HTTP MCP for web AI (claude.ai, ChatGPT)
garmin-bud check          # Live diagnostics against all tools
garmin-bud start          # Start the MCP server (stdio)
garmin-bud auth           # Force re-authentication
garmin-bud cache clear    # Clear cached data
garmin-bud status         # Show session and cache status
garmin-bud --version      # Print version

Configuration

| Variable | Default | Description | |----------|---------|-------------| | GARMIN_EMAIL | — | Garmin Connect email | | GARMIN_PASSWORD | — | Garmin Connect password | | GARMIN_SESSION_PATH | .garmin/session.json | Session token storage | | GARMIN_LOG_PATH | .garmin/mcp.log | Log file path | | GARMIN_CACHE_PATH | .garmin/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) | | GARMIN_MCP_API_KEY | auto-generated | Bearer token for HTTP MCP (garmin-bud serve) | | GARMIN_MCP_HOST | 127.0.0.1 | Bind host for HTTP server | | GARMIN_MCP_PORT | 3847 | Bind port for HTTP server |

Security & privacy

• Credentials live only in your local .env file — never sent to a third party
• Session tokens in .garmin/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's enterprise OAuth API)
• MFA is not supported by the underlying library — disable MFA or use an app-specific password

Troubleshooting

| Issue | Fix | |-------|-----| | Authentication failed | Verify .env credentials, run garmin-bud auth | | MFA enabled on account | Disable MFA or use an app-specific password | | Stale data | Run garmin-bud cache clear | | Rate limited | Wait 60 seconds; cached responses are used when available | | 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 |

Development

npm install
npm run build
npm test          # 33 tests via Node test runner
npm run lint
npm run dev       # Start with auto-reload

Use .nvmrc with nvm/fnm for Node 20. If your project path contains #, use npm test instead of npm run test:vitest.

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
• [ ] Workout comparison
• [ ] Docker image

License

MIT — see LICENSE.

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