Garmin MCP App

Garmin MCP App

MCP App server with interactive React UI for Garmin Connect integration.

Getting Started

git clone https://github.com/chenhunghan/garmin-mcp-app.git
cd garmin-mcp-app
npm install

npm install automatically sets up git hooks via prek:

• commit-msg — enforces Conventional Commits via commitlint
• pre-push — runs lint, format check, typecheck, and tests (same as CI)

Troubleshooting: core.hooksPath

If npm install warns about core.hooksPath, prek cannot install git hooks. Fix it by unsetting the local config:

git config --unset-all --local core.hooksPath
npm run prepare

Testing in Claude Desktop

Run npm run build (one-off) or npm run dev (watch mode for live rebuilds), then add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "garmin-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/garmin-mcp-app/dist/index.js"]
    }
  }
}

Restart Claude Desktop. Ask Claude to check your Garmin auth — it will render the app UI in an iframe and run the real login/MFA flow.

Development

npm run dev        # watch-build server + UI
npm run dev:ui     # standalone UI dev at localhost:5173
npm run test:lib   # run garmin-connect tests
npm run pack       # build + package .mcpb bundle

npm run dev:ui opens http://localhost:5173 with the React UI wired to the real MCP server in-process. You can test login, MFA, and logout against the actual Garmin API without deploying to Claude Desktop.

Supported Data

After authenticating, Claude can access the following from your Garmin Connect account:

• Steps
• Heart rate
• Sleep
• Stress
• Activities
• Training readiness
• Training status & load
• HRV
• Body battery
• Activity details, splits & HR zones
• VO2 Max
• Race predictions
• User settings (age, weight, zones)
• Workout management (create, update, delete, schedule)
• Training effect (aerobic/anaerobic)

Commit Convention

Commits must follow the Conventional Commits format:

type(optional-scope): description

Allowed types: feat, fix, chore, docs, ci, refactor, test