Caddie

The AI caddie that has actually seen every shot you've hit.

Caddie is an MCP server that connects Claude (or any MCP-capable LLM) to your Garmin golf data — every round, every GPS shot, strokes gained, real club distances, plays-like yardages, and the sleep/recovery context behind each score. Ask anything: "why do I blow up on par 5s?", "map my drives at my home course", "does bad sleep actually cost me strokes?"

• Local-first and private: your data syncs once into a DuckDB file on your machine; credentials and health data never leave it.
• Unofficial: Caddie uses the same private API as the Garmin Connect app (via python-garminconnect). It reads your own account only — and it can break whenever Garmin changes things, until the ecosystem catches up. Know that going in.
• Support: best-effort, issues and PRs welcome. By the maker of OneClub.

How it works

Garmin Connect  ──sync──►  local DuckDB cache  ──MCP tools──►  your LLM

Your data is synced once into a local database (~/.caddiemcp/golf.duckdb) and every question is answered from the cache — fast, private, and kind to Garmin's servers. Credentials never leave your machine.

Setup

From source (this directory):

python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/caddie-mcp login              # one-time; MFA supported
.venv/bin/caddie-mcp sync --max-rounds 50

Prefer a browser to a terminal? caddie-mcp login --web opens a local page (127.0.0.1 only) with proper email/password/MFA fields — same token store, friendlier surface.

From the built wheel (no checkout needed — dist/ ships both):

pipx install ./dist/caddie_mcp-1.0.0-py3-none-any.whl   # or pip install
caddie-mcp login && caddie-mcp sync

Once published to PyPI, this becomes uvx caddie-mcp / pipx install caddie-mcp.

Claude Desktop / Claude Code

Add to claude_desktop_config.json (or .mcp.json for Claude Code):

{
  "mcpServers": {
    "caddie-mcp": {
      "command": "/ABSOLUTE/PATH/TO/caddie-mcp",
      "args": ["serve"]
    }
  }
}

Use which caddie-mcp (pipx) or /path/to/caddie-mcp/.venv/bin/caddie-mcp (source install) for the command path. This repo's .mcp.json already wires it up for Claude Code sessions started in this folder.

Remote server (multi-user, HTTP)

The same server runs over streamable-HTTP with bearer-token auth and full per-user isolation — each user gets their own database and Garmin token store under ~/.caddiemcp/users/<name>/ (or $CADDIEMCP_HOME).

caddie-mcp user add marcos          # prints the access token (shown once)
caddie-mcp serve-http --host 0.0.0.0 --port 8724

Users link their own Garmin account in a browser — no admin terminal needed: send them https://your-host/garmin/login, where they enter their access token plus Garmin credentials (two-step MFA supported); tokens land in their private server directory. Admin-assisted caddie-mcp user login <name> still works as a fallback.

Clients connect to http://host:8724/mcp with header Authorization: Bearer <token> — e.g. for Claude Code:

claude mcp add --transport http golf http://host:8724/mcp \
  --header "Authorization: Bearer <token>"

Docker:

python -m build                     # wheel must exist in dist/
docker build -t caddie-mcp .
docker run -d -v caddie_data:/data -p 8724:8724 caddie-mcp
docker exec -it <container> caddie-mcp user add marcos
docker exec -it <container> caddie-mcp user login marcos

Security notes: tokens are 256-bit secrets stored only as SHA-256 hashes and compared in constant time; rotate with caddie-mcp user rotate-token <name>. Run behind TLS (Caddy/nginx/Cloudflare Tunnel) — tokens travel in headers. --no-auth mode exists for localhost-only single-user use and refuses to bind to non-loopback addresses. /health is the only unauthenticated route. The /data volume contains Garmin credentials — treat backups accordingly.

claude.ai custom connectors (OAuth)

claude.ai connects to remote MCP servers via OAuth (dynamic client registration + PKCE), not bearer headers. Enable it with:

caddie-mcp serve-http --host 0.0.0.0 --oauth \
  --public-url https://golf.example.com

Then add https://golf.example.com/mcp as a custom connector in claude.ai. On first connect the user lands on a consent page and pastes their caddie-mcp access token once; after that, OAuth tokens (1 h access + rotating refresh, stored hashed) keep the connection alive, scoped to that user's data. Static bearer tokens keep working alongside OAuth. A real domain with TLS is required — claude.ai will not talk to plain HTTP.

Background sync

In server mode, keep every linked user fresh automatically:

caddie-mcp serve-http --host 0.0.0.0 --sync-every 6h

Users are synced sequentially (incremental, with jitter and per-user error isolation) so the Garmin API never sees a thundering herd.

Claude Desktop Extension

python scripts/build_mcpb.py produces dist/caddie-mcp.mcpb — a double-click install bundle for Claude Desktop that launches the published package via uvx. Requires uv on the machine and the package on PyPI; the one-time uvx caddie-mcp login still happens in a terminal (credentials never pass through the desktop app).

Publishing to PyPI (maintainer)

.venv/bin/python -m build          # sdist + wheel into dist/
pipx run twine upload dist/*       # needs a PyPI API token

Data quality & repair

caddie-mcp repair re-derives every computed field across the cache with no Garmin calls (club names, lie/shot-type normalization, GPS-to-pin distances, GIR/fairway inference). It runs automatically at the end of every sync, so you only need it manually after upgrading the connector.

Known Garmin quirks handled: watches report TEEBOX/TEE/UNKNOWN enums; putts are often a per-hole count with no green shots; the end position of green-reaching shots is snapped to the pin (so post-shot proximity on green hits is honestly NULL, and strokes-gained putting uses a flagged estimate).

Tools

Tool	What it answers
garmin_status	Am I connected? How much is cached vs still on Garmin?
sync_garmin_data	Pull rounds/shots/clubs from Garmin — chunked (25/call, reports rounds_remaining) so full multi-year histories load safely from chat
list_rounds	"Show my recent rounds" — compact summaries
get_round	One round in depth: scorecard, holes, shots
get_shots	Shot-level GPS/club/lie data; format="geojson" for maps
get_club_stats	Real measured distances per club vs Garmin's estimates
get_strokes_gained	Broadie strokes gained per round: off-tee / approach / short game / putting, vs your handicap level or scratch
get_performance_stats	~40 PGA-style stats (driving, GIR by distance, scrambling, putting, scoring) with optional handicap benchmarks
get_handicap	WHS-style index, counting differentials, and trend
get_course_intel	Per-hole difficulty and usual tee club at one course
get_health_context	Sleep, HRV, Body Battery, readiness, and stress for a round's date
correlate_health_performance	"Do I score worse on bad sleep?" — paired data + honest correlation
query_golf_data	Any question, as read-only SQL over the cache

Sync also fills daily_health (4 extra Garmin calls per round date): sleep score/duration, resting HR, HRV status, Body Battery range, training readiness, stress, steps — plus round-window enrichment on each round: Body Battery at tee time and drain during play, average/max heart rate and stress during the round, and the round's weather (temperature, wind, humidity, conditions) via its matched Garmin activity.

When Garmin sends no dispersion data, shot miss offsets (dx/dy) are derived from GPS geometry: drives laterally vs the tee→pin line, approaches/chips relative to the pin — powering miss-direction and miss-tendency stats on any watch with shot GPS.

Every shot also gets plays-like distance: terrain elevations for shot and pin positions come from the free Open-Meteo elevation API (cached forever in the local DB), and plays_like_yds applies the standard 1:1 uphill/downhill heuristic — so "my 150-yd shots" can be analyzed by what they actually played as.

Prompts (packaged workflows): post_round_report, practice_plan, course_strategy, health_check_in, season_review.

Resources: schema://data-dictionary (columns, units, enums), docs://metric-definitions (how every stat is computed), and docs://getting-started (recommended tool flow).

Conventions

• Distances in yards, coordinates in decimal degrees, times in ISO 8601.
• Lies: tee | fairway | rough | sand | green | recovery | penalty.
• Shot types: drive | approach | chip | putt | penalty.
• Unknown values are NULL, never fabricated — the last shot of a hole has no measured end-distance, and tools say so.

Security notes

• Garmin tokens live at ~/.garminconnect (mode 0600) — treat like a password.
• The SQL tool is read-only, single-statement, SELECT-only, and capped.
• This is an unofficial connector for your own Garmin data.

Development

.venv/bin/python -m pytest tests/ -q

---

mcp-name: io.github.mbrionesalvarez/caddie-mcp