{
  "markdown": "<!-- mcp-name: io.github.bjornj12/golf-coach -->\n\n# Golf Coach\n\n**A golf coach that trains you purely on your stats — round after round, closer to scratch.**\n\nGolf Coach logs into **Trackman Golf** with your own account and turns your\nstats — course rounds, practice sessions, shot-level launch-monitor data, club\ngapping, and handicap — into a diagnosis of where you're losing strokes, then\nhands you a specific practice plan with drills and YouTube links for your next\nsession and grades your progress over time. It ships as an MCP server (the data\ntools) plus Claude **skills** (the coaching brain).\n\n## What you get\n\nYou don't read the charts — you get a coach. Point it at your Trackman data and it:\n\n- **Finds where you're actually losing strokes** — not \"work on your irons,\" but\n  *\"your driver has a two-way miss spreading landings across a ~115 m corridor —\n  the speed is real, the face isn't yet.\"*\n- **Hands you one specific session** — clubs, distances, reps, a Trackman target,\n  and a drill with a real YouTube link. Stuck indoors? It has an at-home, no-ball\n  routine too.\n- **Grades your progress** — it saves the plan and checks your next session\n  against it, so you actually know whether it worked.\n- **Shows you the picture** — an animated view of your ball flight, the swing\n  path behind the miss, and how close you are to each target.\n\n![A Golf Coach session — driver-dispersion diagnosis with the swing-path cause, progress-vs-target bars, and drills to fix it](docs/media/sample-analysis.png)\n\n*A real session diagnosis: what's wrong, why, how close you are to your targets, and exactly what to practice next.*\n\n> **Name note.** \"Golf Coach\" is the product name. The technical ids stay\n> `golf-coach` (MCP server / plugin) and `golf-coach` (the published\n> package), so existing installs keep working.\n\n> [!IMPORTANT]\n> **Unofficial.** This project is not affiliated with or endorsed by Trackman.\n> It talks to Trackman's **private** web API using a token from *your own*\n> authenticated session, and automates a browser login on your behalf. This may\n> conflict with Trackman's Terms of Service — use it on your own account, at your\n> own risk. Never use it to access anyone else's data.\n\n## Design boundary\n\n- **MCP server** = raw data fetch + auth only. No opinions.\n- **Skills** = all the coaching (analysis, plans, drills).\n\nSee [`CLAUDE.md`](./CLAUDE.md) for the full architecture and auth/secret rules.\n\n## Install\n\nPick the path for how you use Claude. Each takes about two minutes, then do the\none-time [Authentication](#authentication-one-time) step.\n\n### 🖥️ Claude Desktop — one-click (recommended, no terminal)\n\n1. **Download [`golf-coach.mcpb`](https://github.com/bjornj12/golf-coach/releases/latest/download/golf-coach.mcpb)** (from the [latest release](https://github.com/bjornj12/golf-coach/releases/latest)).\n2. Open **Claude Desktop → Settings → Extensions**, drag the file in (or\n   double-click it), and click **Install**. Leave the token field **blank**.\n3. In a chat, say **\"log in to Trackman\"** → a **browser window opens** → sign in\n   once with your Trackman email + password (Apple / Google sign-in works too).\n   The window **stays open until you finish** — take your time, it won't close on\n   its own. When you're done, tell Claude and it confirms you're signed in.\n4. Ask Claude: *\"What's my Trackman handicap?\"*\n\nNothing to install and no config to edit — Claude Desktop runs everything and\nopens the sign-in browser for you. (First sign-in may take a moment if it needs\nto fetch a browser. You may also see an \"unsigned extension\" note — expected for\none installed from a file.)\n\n**Platforms:** macOS, Linux, and **Windows** — Claude Desktop runs the server via\n`uv` on all three, and the browser sign-in uses Playwright (cross-platform). One\ncaveat on Windows: the local token/data files are protected by your Windows user\nprofile (ACLs) rather than POSIX `0600` modes. The optional cron/launchd\nauto-refresh script is macOS/Linux only — on Windows use Task Scheduler, or just\nre-run the in-app \"log in to Trackman\" when the ~7-day token lapses.\n\n### ⌨️ Claude Code — plugin (server **and** coaching skills)\n\n```text\n/plugin marketplace add bjornj12/golf-coach\n/plugin install golf-coach@golf-coach\n```\n\nInstalls the MCP server (run via `uvx`) and all ten coaching skills.\n\n### 🔌 Other MCP clients (or Claude Desktop without the extension)\n\nRequires [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`).\nAdd this to your client's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"golf-coach\": { \"command\": \"uvx\", \"args\": [\"golf-coach\"] }\n  }\n}\n```\n\n> For **Claude Desktop's manual config** (`~/Library/Application Support/Claude/claude_desktop_config.json`\n> on macOS), use the **absolute path** to `uvx` — e.g. `/opt/homebrew/bin/uvx` —\n> because the app doesn't inherit your shell `PATH`. The `.mcpb` install above\n> avoids this entirely.\n\n## Authentication (one-time)\n\nThe server needs to sign in to **your** Trackman account. Trackman has no public\nlogin API, so it captures a token from a real signed-in browser session once;\nit's then cached locally and refreshes itself. Your password is never seen or\nstored by the tool, and nothing leaves your machine.\n\n### Easiest — just ask Claude to log in (Claude Desktop / Claude Code)\n\nSay **\"log in to Trackman.\"** A browser window opens (an isolated profile, not\nyour normal Chrome); sign in once, at your own pace — the window is driven by a\nbackground task, so it **stays open until you're done** and won't be closed out\nfrom under you (even a slow Apple/Google 2FA is fine). When you've finished,\ntell Claude and it confirms. The token caches at `~/.golf-coach/token.json`\n(mode `0600`) and the MCP uses it automatically from then on. No terminal, no\ntoken to copy — the extension fetches a browser itself if you don't have one.\n\n### Terminal alternative (CLI users)\n\n```bash\nuv tool install \"golf-coach[login]\"\ngolf-coach login              # opens a browser; sign in once\ngolf-coach login --headless   # silent refresh later (tokens last ~7 days)\nscripts/install-refresh-schedule.sh   # optional: auto-refresh twice weekly\n```\n\n### Advanced — paste a token\n\n`portal.trackmangolf.com` → DevTools → **Network** → a `graphql` request → copy\nthe `Authorization: Bearer …` value → paste into the extension's **Trackman\ntoken** field (or set `TRACKMAN_TOKEN`). Tokens expire after ~7 days, so the\nsign-in flows above are easier.\n\n### Verify it worked\n\nAsk Claude *\"Am I signed in to Trackman?\"* — it runs `auth(action=\"status\")` and\nreplies with your name (never the token).\n\n## MCP tools\n\nAll tools return **raw data only**; the skills interpret it.\n\n**8 tools.** `trackman` and `gamebook` each take an `action` (so the agent\npicks one tool with a mode rather than many near-identical tools).\n\n**Setup:** `setup` — one call returns an always-on coach **system prompt** (for a\nProject), the **skills** as upload-ready files, and per-client steps. There's a\nmatching `setup` prompt in the picker.\n\n**Auth:** `auth(action: status | login, source?)`\n\n**Trackman data (read-only):** `trackman(action: profile | handicap | sessions\n| session | rounds | clubs | summary)` — profile+handicap, handicap history,\nactivity list, one activity in full (incl. shot-level metrics), course rounds,\nclub gapping, activity counts.\n\n**Gamebook rounds (local, deterministic):** `gamebook(action: save | list |\nget | compare)` — on-course rounds ingested from Golf GameBook screenshots,\nrolling last 5, coverage-aware (only score-per-hole is trusted).\n\n**Cross-source synthesis (local, deterministic):** `synthesize()` — aligns\nTrackman's and GameBook's per-source Findings by skill area (no verdict; see\n`CLAUDE.md`'s \"Sources & normalization\").\n\n**Session analysis (local, deterministic):** `session_analysis(action: analyze | get | list)`\n\n**Training-plan memory:** `training_plan(action: save | next | list | done | verify)`\n\n**Visualization:** `build_visualization` (self-contained animated HTML artifact)\n\nSee [`CLAUDE.md`](./CLAUDE.md) for the full table and backing GraphQL.\n\n## Skills (coaching brain)\n\nThe skills under [`skills/`](./skills) are delivered two ways:\n\n- **Claude Code:** installed automatically with the plugin.\n- **Any MCP client (incl. Claude Desktop):** the server **serves them as MCP\n  prompts**, so they show up in your client's prompt picker — no separate install.\n\n| Skill | What it does |\n|-------|--------------|\n| `trackman-stats-analysis` | Diagnose weaknesses from the data |\n| `golf-coaching` | Turn the diagnosis into an actionable practice plan (visual-first; auto-grades progress) |\n| `drill-library` | Curated drills + vetted links — incl. **at-home / no-ball** drills — plus live search |\n| `golf-practice-at-home` | Build a daily **no-ball** routine for a diagnosed fault, animated per drill |\n| `at-home-practice-feedback` | A single mobile-first **drill card** with built-in feedback: prop, validation checkpoint, budget tier, video |\n| `trackman-session-analyzer` | Ingest + normalize recent sessions |\n| `gamebook-screenshot-analysis` | Ingest GameBook round screenshots into a coverage-aware round record; scoring-led progress that feeds the coach |\n| `swing-video-check` | Frame-by-frame visual check of a filmed swing (one angle per clip) against the current practice card |\n| `grip-check` | Grade the grip (too weak / too strong) from two face-forward photos — the coach's gate before any new prescription |\n| `trackman-visualizer` | Animate a diagnosis (or a single drill's mechanics) as an HTML artifact |\n\nTo check a filmed swing: drop a clip named `DATE_CLUB_ACTION.mp4` (e.g.\n`2026-07-17_driver_grip-reset.mp4`) into the project in Claude Code and say\n\"check my swing\" — you get an angle-scoped checklist and one swing thought\n(needs `ffmpeg`).\n\n(`trackman-api-discovery` is a project/dev skill and isn't served as a prompt.)\n\n## Development\n\n```bash\nuv venv && uv pip install -e '.[login,dev]'   # [login] = Playwright, [dev] = test/lint tools\n\ngolf-coach                       # run the MCP server (stdio)\nuv run python scripts/validate.py  # sanity-check stats coverage with your token\n\nuv run pytest        # tests\nuv run ruff check    # lint\nuv run mypy          # type-check\n```\n\nReleasing (PyPI + MCP Registry + the Desktop `.mcpb`) is one command —\n`scripts/release.sh patch` — see [`PUBLISHING.md`](./PUBLISHING.md).\n\n## License\n\n[MIT](./LICENSE)\n",
  "bytes": 10434,
  "sha": "e37842ac98185d66c3ed0730876f556d8e2059f52121ffd031c7f9cce5ac1259",
  "repo_slug": "bjornj12/golf-coach",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bjornj12_golf_coach_82c9e88a/readme"
}