The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Caddie MCP listing page.
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?"
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.
From source (this directory):
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):
Once published to PyPI, this becomes uvx caddie-mcp / pipx install caddie-mcp.
Add to claude_desktop_config.json (or .mcp.json for Claude Code):
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.
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).
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:
Docker:
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 connects to remote MCP servers via OAuth (dynamic client registration + PKCE), not bearer headers. Enable it with:
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.
In server mode, keep every linked user fresh automatically:
Users are synced sequentially (incremental, with jitter and per-user error isolation) so the Garmin API never sees a thundering herd.
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).
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).
| 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).
tee | fairway | rough | sand | green | recovery | penalty.drive | approach | chip | putt | penalty.NULL, never fabricated — the last shot of a hole has no
measured end-distance, and tools say so.~/.garminconnect (mode 0600) — treat like a password.mcp-name: io.github.mbrionesalvarez/caddie-mcp