Caddie MCP server

by mbrionesalvarez·io.github.mbrionesalvarez/caddie-mcp·v1.0.1

No reviews yet

Your Garmin golf data in Claude: GPS shots, strokes gained, club distances, health context

A88/100grade A

Write a review Install

What users say

No reviews yet

Be the first

Safety scan

A88/100

full report

Adoption

New

0 stars17 downloads/wk

Reviews

Write one

Nobody has reviewed Caddie yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

Caddie tools (13, 1 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

correlate_health_performance
Does recovery (or weather) affect your golf? Joins each round to its health/conditions data and computes a Pearson correlation. Daily metrics (sleep_score, hrv, readiness...) come from the night/day around the round; round-window metrics (bb_at_tee, avg_hr_during_round, avg_stress_during_ round, temp_c, wind_speed_mph) are measured DURING the round itself. Returns the paired table, r, and an hones
garmin_status
Check connector health: Garmin auth state, last sync, cached data coverage (rounds, shots, GPS %, club %). Call this first in a session.
get_club_stats
Per-club performance over the last N rounds: measured avg/min/max/ stddev carry distance (excludes putts and penalties), sample size, usage share, lateral miss bias from Garmin's dx offsets, plus Garmin's own average and 'advice' distances for comparison.
get_course_intel
Personal course intelligence for one course (name substring match): per-hole scoring average vs par, hardest and easiest holes, most common tee club per hole, and round history there. Use for strategy questions like 'how should I play X next time?'.
get_handicap
WHS-style Handicap Index: best-N-of-20 differentials, which rounds count, and the index trend over time. Needs rounds with tee rating and slope (Garmin records these when a tee box is selected on the watch).
get_health_context
Health context for a round or date (YYYY-MM-DD): sleep score and duration the night before, HRV status, Body Battery range, training readiness, average stress, resting HR, steps. With round_id, also returns the round summary so performance and recovery sit side by side. NULL fields mean the watch/feature didn't record — say so, don't guess.
get_performance_stats
PGA-style performance stats over the last N rounds: driving distance/ accuracy + miss direction, GIR and proximity by distance bucket, scrambling and sand saves, putting (make % by feet, 3-putt avoidance), scoring (par 3/4/5 averages, bounce-back, distribution). Optionally pass benchmark_handicap to compare every metric against that handicap level.
get_round
Get one round in depth: header, hole-by-hole scorecard, and optionally every shot. round_id comes from list_rounds. Prefer get_shots (with filters or geojson) when the goal is shot analysis or mapping.
get_shots
Get shot-level data (GPS, club, lie, distance, miss offsets dx/dy). Filter by round_id, holes, club name substring, or shot_type (drive|approach|chip|putt|penalty). format="geojson" returns a FeatureCollection (shot LineStrings + pin Points) ready for Mapbox or Leaflet — ideal for shot maps and dashboards.
get_strokes_gained
Strokes Gained (Broadie method) per round: total plus off-tee / approach / short-game / putting. baseline: "auto" grades each round against the player's own handicap level; or force one of scratch, 5hcp, 10hcp, 15hcp, 20hcp, bogey (scratch = the number seen on TV). estimated_share > 0 means some shots lacked GPS and used inferred lies/distances — hedge conclusions accordingly.
list_rounds
List golf rounds, newest first, as compact summaries (date, course, score, putts, fairways, GIR, ratings). Dates are YYYY-MM-DD; course is a case-insensitive substring match. Use get_round for hole-by-hole detail.
query_golf_datawrite action
Run a read-only SQL SELECT over the golf database (DuckDB dialect). Tables: rounds, holes, shots, clubs, daily_health. Read the schema://data-dictionary resource for columns, units, and enums. Single statement, SELECT/WITH only, capped at 200 rows — aggregate server-side instead of selecting raw rows when possible.
sync_garmin_data

Public scan report

scanner v0.1.10 · 2026-11-04 · same rubric, same numbers if you re-run it

no findings

Code scan25 source files scanned25/25
–Live reliabilityno gateway calls yet and no remote to proben/a
–Tool poisoningtools not inspected (local package is not executed); not countedn/a
Auth qualitylocal package, no credentials required12/15
Maintenancelast push 85 days ago12/15
Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Overall 88/100. Components that don't apply are left out of the denominator. Any critical finding is an F.Rubric Appeal a finding JSON

How Caddie compares

Against every graded MCP server, from our own scans and uptime checks. Updated after each scan run.

Safety score: 88/100; higher than 75% of 48,255 servers
Tools: 13; the typical server has 7
Tools that change things: 8%; typical: 0%. Fewer write tools means less an agent can break
Downloads a week: 17; more than 5% of 12,191 servers with a package

What its tools let an agent do: 11 read · 2 change

Install Caddie in Claude Code, Cursor or VS Code

claude mcp add caddie-mcp -- uvx caddie-mcp

Add to Cursor

What the publisher says

From the Caddie repository's README, as published. We do not edit it. Read it on GitHub

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?"

your machine; credentials and health data never leave it.

Local-first and private: your data syncs once into a DuckDB file on

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.

Unofficial: Caddie uses the same private API as the Garmin Connect

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 claudedesktopconfig.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// (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 still works as a fallback.

Clients connect to http://host:8724/mcp with header Authorization: Bearer — 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

Shortened. The full README is on GitHub.

Nothing above is checked by us. What we check is on the safety report.

Caddie: common questions

Is Caddie MCP server safe?: Yes, by our scan: it is graded A (88/100). Read the Caddie safety report
How do I install Caddie?: It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.
Does Caddie need an API key?: Not as far as the registry entry and our scan can tell: no credentials are declared or required.
Is Caddie maintained?: The last commit was 85 days ago (2026-08-11). The latest release is v1.0.1.
How does Caddie compare with other MCP servers?: safety score 88/100 (higher than 75% of 48,255 servers); tools 13 (the typical server has 7); tools that change things 8% (typical: 0%. Fewer write tools means less an agent can break). Full comparison.