Garmin App

• Your credentials stay private. You sign in through a secure login form rendered inside Claude Desktop. The login and MFA tools are marked as app-only (visibility: ["app"]), meaning Claude (the LLM) cannot call them and never sees your email, password, or MFA code.
• Claude doesn't know who you are. The LLM only receives the health/fitness data you ask for (steps, sleep, etc.) — it has no access to your Garmin account credentials or OAuth tokens.
• Tokens are stored locally. OAuth tokens are saved on your machine at ~/.garminconnect/ with restrictive file permissions (0600). They are never sent anywhere other than the Garmin Connect API.
• You can log out anytime. Logging out clears all saved tokens from your machine.

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

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.

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.

Architecture

• MCP Server (src/server.ts) — Node.js server over stdio, registers tools + UI resource
• React UI (src/app.tsx) — Rendered in host's sandboxed iframe, communicates via postMessage
• garmin-connect (packages/garmin-connect/) — TypeScript client library for Garmin Connect OAuth + API

Commit Convention

Commits must follow the Conventional Commits format:

type(optional-scope): description

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