Metadata-Version: 2.4
Name: trackman-mcp
Version: 0.2.2
Summary: MCP server that fetches a user's Trackman Golf stats (handicap, rounds, practice, shots, club gapping).
Project-URL: Homepage, https://github.com/bjornj12/trackman-mcp-client
Project-URL: Repository, https://github.com/bjornj12/trackman-mcp-client
Project-URL: Issues, https://github.com/bjornj12/trackman-mcp-client/issues
Author-email: Bjorn Jonsson <bjorn@avo.sh>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,golf,llm,mcp,model-context-protocol,trackman
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: login
Requires-Dist: playwright>=1.40; extra == 'login'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.bjornj12/trackman-mcp -->

# trackman-mcp

An MCP server that logs into **Trackman Golf** with your own account and exposes
your stats — course rounds, practice sessions, shot-level launch-monitor data,
club gapping, and handicap — as MCP tools. On top of that, a set of Claude
**skills** act as your golf coach: they diagnose your weaknesses and hand you a
specific practice plan with drills and YouTube links for your next session.

> [!IMPORTANT]
> **Unofficial.** This project is not affiliated with or endorsed by Trackman.
> It talks to Trackman's **private** web API using a token from *your own*
> authenticated session, and automates a browser login on your behalf. This may
> conflict with Trackman's Terms of Service — use it on your own account, at your
> own risk. Never use it to access anyone else's data.

## Design boundary

- **MCP server** = raw data fetch + auth only. No opinions.
- **Skills** = all the coaching (analysis, plans, drills).

See [`CLAUDE.md`](./CLAUDE.md) for the full architecture and auth/secret rules.

## Install

Pick the path for how you use Claude. Each takes about two minutes, then do the
one-time [Authentication](#authentication-one-time) step.

### 🖥️ Claude Desktop — one-click (recommended, no terminal)

1. **Download [`trackman-golf.mcpb`](https://github.com/bjornj12/trackman-mcp-client/releases/latest/download/trackman-golf.mcpb)** (from the [latest release](https://github.com/bjornj12/trackman-mcp-client/releases/latest)).
2. Open **Claude Desktop → Settings → Extensions**, drag the file in (or
   double-click it), and click **Install**. Leave the token field **blank**.
3. In a chat, say **"log in to Trackman"** → a **browser window opens** → sign in
   once with your Trackman email + password. That's it.
4. Ask Claude: *"What's my Trackman handicap?"*

Nothing to install and no config to edit — Claude Desktop runs everything and
opens the sign-in browser for you. (First sign-in may take a moment if it needs
to fetch a browser. You may also see an "unsigned extension" note — expected for
one installed from a file.)

### ⌨️ Claude Code — plugin (server **and** coaching skills)

```text
/plugin marketplace add bjornj12/trackman-mcp-client
/plugin install trackman-golf@trackman-golf
```

Installs the MCP server (run via `uvx`) and all six coaching skills.

### 🔌 Other MCP clients (or Claude Desktop without the extension)

Requires [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`).
Add this to your client's MCP config:

```json
{
  "mcpServers": {
    "trackman-golf": { "command": "uvx", "args": ["trackman-mcp"] }
  }
}
```

> For **Claude Desktop's manual config** (`~/Library/Application Support/Claude/claude_desktop_config.json`
> on macOS), use the **absolute path** to `uvx` — e.g. `/opt/homebrew/bin/uvx` —
> because the app doesn't inherit your shell `PATH`. The `.mcpb` install above
> avoids this entirely.

## Authentication (one-time)

The server needs to sign in to **your** Trackman account. Trackman has no public
login API, so it captures a token from a real signed-in browser session once;
it's then cached locally and refreshes itself. Your password is never seen or
stored by the tool, and nothing leaves your machine.

### Easiest — just ask Claude to log in (Claude Desktop / Claude Code)

Say **"log in to Trackman."** A browser window opens (an isolated profile, not
your normal Chrome); sign in once. The token caches at `~/.trackman-mcp/token.json`
(mode `0600`) and the MCP uses it automatically from then on. No terminal, no
token to copy — the extension fetches a browser itself if you don't have one.

### Terminal alternative (CLI users)

```bash
uv tool install "trackman-mcp[login]"
trackman-mcp login              # opens a browser; sign in once
trackman-mcp login --headless   # silent refresh later (tokens last ~7 days)
scripts/install-refresh-schedule.sh   # optional: auto-refresh twice weekly
```

### Advanced — paste a token

`portal.trackmangolf.com` → DevTools → **Network** → a `graphql` request → copy
the `Authorization: Bearer …` value → paste into the extension's **Trackman
token** field (or set `TRACKMAN_TOKEN`). Tokens expire after ~7 days, so the
sign-in flows above are easier.

### Verify it worked

Ask Claude *"Am I signed in to Trackman?"* — it runs the `authenticate` tool and
replies with your name (never the token).

## MCP tools

All tools return **raw data only**; the skills interpret it.

**12 tools.** The CRUD clusters take an `action` (so the agent isn't choosing
among many near-identical tools); the data reads stay discrete.

**Setup:** `setup` — one call returns an always-on coach **system prompt** (for a
Project), the **skills** as upload-ready files, and per-client steps. There's a
matching `setup` prompt in the picker.

**Auth:** `auth(action: status | login)`

**Data (read-only):** `get_profile` · `get_handicap` · `list_sessions` ·
`get_session` (full detail incl. shot-level metrics) · `get_course_rounds` ·
`get_club_stats` · `get_activity_summary`

**Session analysis (local, deterministic):** `session_analysis(action: analyze | get | list)`

**Training-plan memory:** `training_plan(action: save | next | list | done | verify)`

**Visualization:** `build_visualization` (self-contained animated HTML artifact)

See [`CLAUDE.md`](./CLAUDE.md) for the full table and backing GraphQL.

## Skills (coaching brain)

The skills under [`skills/`](./skills) are delivered two ways:

- **Claude Code:** installed automatically with the plugin.
- **Any MCP client (incl. Claude Desktop):** the server **serves them as MCP
  prompts**, so they show up in your client's prompt picker — no separate install.

| Skill | What it does |
|-------|--------------|
| `trackman-stats-analysis` | Diagnose weaknesses from the data |
| `golf-coaching` | Turn the diagnosis into an actionable practice plan |
| `drill-library` | Curated drills + vetted YouTube links, plus live search |
| `trackman-session-analyzer` | Ingest + normalize recent sessions |
| `trackman-visualizer` | Animate a diagnosis as an HTML artifact |

(`trackman-api-discovery` is a project/dev skill and isn't served as a prompt.)

## Development

```bash
uv venv && uv pip install -e '.[login,dev]'   # [login] = Playwright, [dev] = test/lint tools

trackman-mcp                       # run the MCP server (stdio)
uv run python scripts/validate.py  # sanity-check stats coverage with your token

uv run pytest        # tests
uv run ruff check    # lint
uv run mypy          # type-check
```

Releasing (PyPI + MCP Registry + the Desktop `.mcpb`) is one command —
`scripts/release.sh patch` — see [`PUBLISHING.md`](./PUBLISHING.md).

## License

[MIT](./LICENSE)
