trackman-mcp

高尔夫教练

一位完全根据你的数据指导你训练的高尔夫教练——一轮又一轮，逐步接近标准杆水平。

高尔夫教练会使用你自己的账户登录 Trackman Golf，将你的数据——球场回合、练习课程、逐杆的发射监测数据、球杆距离差和差点——转化为一份诊断，指出你在哪些方面丢了杆数；然后为你的下一次练习制定具体计划，附上训练方法和 YouTube 链接，并持续评估你的进步。它由 MCP 服务（数据工具）和 Claude 技能（教练核心）组成。

你将获得什么

你不用自己看图表——你会得到一位教练。让它读取你的 Trackman 数据，它就会：

• 找出你真正丢杆的地方——不是“练练铁杆”，而是 “你的开球木左右失误都有，落点分布横跨约 115 m 的区域——你的速度不错，但杆面控制还不够稳定。”
• 为你安排一节具体的练习——包括球杆、距离、次数、Trackman 目标，以及附有真实 YouTube 链接的训练方法。困在室内？它也有无需球的居家训练方案。
• 评估你的进步——它会保存计划，并据此检查你的下一次练习，让你确切知道训练是否有效。
• 展示你的击球情况——通过动态视图展示球的飞行轨迹、导致失误的挥杆路径，以及你距离各项目标还有多远。

一次真实的训练诊断：问题所在、问题成因、你距离目标有多远，以及下一步该具体练什么。

名称说明。“Golf Coach”是产品名称。技术 ID 保持为 golf-coach（MCP 服务 / 插件）和 golf-coach（已发布的 软件包），因此现有安装仍可正常使用。

重要

非官方项目。本项目与 Trackman 无关联，也未获其认可。 它使用来自你自己的已认证会话的令牌，调用 Trackman 的私有 Web API，并代你自动执行浏览器登录。这可能与 Trackman 的服务条款冲突——请仅在你自己的账户上使用，并自行承担风险。切勿用它访问他人的数据。

设计边界

• MCP 服务 = 仅获取原始数据 + 身份验证。不提供建议。
• 技能 = 负责全部教练工作（分析、计划、训练方法）。

完整架构和身份验证/机密信息规则，请参阅 CLAUDE.md。

安装

根据你使用 Claude 的方式选择安装路径。每种方式大约需要两分钟，然后完成一次性身份验证步骤。

🖥️ Claude Desktop — 一键安装（推荐，无需终端）

1. 下载 golf-coach.mcpb（从最新版本下载）。
2. 打开 Claude Desktop → Settings → Extensions，将文件拖入（或双击），然后点击 Install。将令牌字段留空。
3. 在聊天中说 “登录 Trackman” → 浏览器窗口会打开 → 使用 Trackman 邮箱和密码登录一次（也支持 Apple / Google 登录）。 登录完成前，窗口会一直保持打开，请慢慢操作，它不会自行关闭。完成后，告诉 Claude，它会确认你已登录。
4. 询问 Claude：“我的 Trackman 差点是多少？”

无需安装其他内容，也无需编辑配置 — Claude Desktop 会运行所有内容，并为你打开登录浏览器。（如果需要获取浏览器，首次登录可能需要稍等片刻。你也可能会看到“未签名扩展”的提示 — 从文件安装时这是正常现象。）

平台： macOS、Linux 和 Windows — Claude Desktop 会在这三个平台上通过 uv 运行服务，浏览器登录使用 Playwright（跨平台）。Windows 有一项注意事项：本地令牌和数据文件由 Windows 用户配置文件（ACL）保护，而非使用 POSIX 0600 权限模式。可选的 cron/launchd 自动刷新脚本仅支持 macOS/Linux — 在 Windows 上请使用任务计划程序，或者在约 7 天后令牌过期时，重新通过应用内的“登录 Trackman”操作登录。

⌨️ Claude Code — 插件（MCP 服务和教练技能）

/plugin marketplace add bjornj12/golf-coach
/plugin install golf-coach@golf-coach

安装 MCP 服务（通过 uvx 运行）和全部十项教练技能。

🔌 其他 MCP 客户端（或未安装扩展的 Claude Desktop）

需要安装 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）。 将以下内容添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "golf-coach": { "command": "uvx", "args": ["golf-coach"] }
  }
}

对于 Claude Desktop 的手动配置（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json），请使用 uvx 的绝对路径 — 例如 /opt/homebrew/bin/uvx — 因为应用不会继承你的 shell PATH。使用上面的 .mcpb 安装方式则完全无需处理此问题。

身份验证（仅需一次）

服务需要登录到你的 Trackman 账户。Trackman 没有公开的登录 API，因此它会从一次真实的已登录浏览器会话中获取令牌；之后令牌会缓存在本地并自动刷新。工具不会查看或存储你的密码，任何内容都不会离开你的设备。

最简单的方法 — 直接让 Claude 登录（Claude Desktop / Claude Code）

说 “登录 Trackman”。浏览器窗口会打开（使用隔离的配置文件，不是你平时使用的 Chrome）；登录一次即可，请按自己的节奏操作 — 窗口由后台任务驱动，因此会一直保持打开，直到你完成操作，不会在你操作时被关闭（即使 Apple/Google 双重身份验证较慢也没问题）。完成后，告诉 Claude，它会确认你已登录。令牌会缓存在 ~/.golf-coach/token.json（模式 0600）中，之后 MCP 会自动使用该令牌。如果你没有浏览器，扩展会自行获取；无需使用终端，也无需复制令牌。

终端替代方式（CLI 用户）

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

高级 — 粘贴令牌

进入 portal.trackmangolf.com → DevTools → Network → 找到一个 graphql 请求 → 复制 Authorization: Bearer … 值 → 粘贴到扩展的 Trackman token 字段（或设置 TRACKMAN_TOKEN）。令牌会在约 7 天后过期，因此使用上面的登录流程会更方便。

验证是否成功

询问 Claude：“我已登录 Trackman 吗？” — 它会运行 auth(action="status")，并回复你的姓名（不会显示令牌）。

MCP 工具

所有工具仅返回原始数据；由技能负责解读。

8 个工具。 trackman 和 gamebook 都接收一个 action（因此 Agent 可以选择带有某种模式的单个工具，而不是多个几乎相同的工具）。

设置： setup — 一次调用即可返回始终启用的教练系统提示词（用于 Project）、可直接上传的技能文件，以及各客户端的操作步骤。选择器中也有对应的 setup 提示词。

身份验证： auth(action: status | login, source?)

Trackman 数据（只读）： trackman(action: profile | handicap | sessions | session | rounds | clubs | summary) — 个人资料和差点、差点历史、活动列表、完整的单项活动（含每杆指标）、球场回合、球杆距离间隔、活动计数。

Gamebook 回合（本地、确定性）： gamebook(action: save | list | get | compare) — 从 Golf GameBook 截图导入的实地回合，滚动保留最近 5 个，考虑数据覆盖范围（仅可信任逐洞得分）。

跨来源综合（本地、确定性）： synthesize() — 按技能领域对齐 Trackman 和 GameBook 各自的 Findings（不做结论；参见 CLAUDE.md 中的 “Sources & normalization”）。

训练分析（本地、确定性）： session_analysis(action: analyze | get | list)

训练计划记忆： training_plan(action: save | next | list | done | verify)

可视化： build_visualization（自包含的动画 HTML 成品）

完整表格和底层 GraphQL 见 CLAUDE.md。

技能（教练大脑）

skills/ 下的技能通过两种方式提供：

• Claude Code： 随插件自动安装。
• 任何 MCP 客户端（包括 Claude Desktop）： 服务端会将其作为 MCP 提示词提供，因此它们会显示在客户端的提示词选择器中——无需单独安装。

技能	功能
trackman-stats-analysis	根据数据诊断弱项
golf-coaching	将诊断结果转化为可执行的练习计划（优先采用可视化；自动评估进度）
drill-library	精选练习 + 经验证的链接——包括居家／无球练习——以及实时搜索
golf-practice-at-home	针对已诊断的问题制定每日无球训练流程，并为每项练习添加动画
at-home-practice-feedback	一张移动端优先的练习卡片，内置反馈：辅助道具、验证检查点、预算等级、视频
trackman-session-analyzer	导入并规范化近期训练记录
gamebook-screenshot-analysis	将 GameBook 回合截图导入为考虑数据覆盖范围的回合记录；以成绩为主的进度追踪会反馈给教练
swing-video-check	逐帧目视检查拍摄的挥杆视频（每段视频一个角度），并与当前练习卡片对照
grip-check	根据两张正对镜头的照片评估握杆（过弱／过强）——这是教练开出任何新训练方案前的把关环节
trackman-visualizer	将诊断结果（或单项练习的动作机制）制作成 HTML 动画成品

如需检查拍摄的挥杆视频，请将名为 DATE_CLUB_ACTION.mp4 的片段（例如 2026-07-17_driver_grip-reset.mp4）放入 Claude Code 中的项目，然后说 “check my swing”——你会得到一份限定角度的检查清单和一个挥杆提示 （需要 ffmpeg）。

（trackman-api-discovery 是项目／开发技能，不会作为提示词提供。）

开发

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

golf-coach                       # 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

发布到 PyPI、MCP Registry 和 Desktop .mcpb 只需一条命令—— scripts/release.sh patch — 参见 PUBLISHING.md。

许可证

MIT