opengolfapi

@opengolfapi/mcp-server

为 AI Agent 打造的高尔夫——高尔夫领域的开放数据层。 免费向你的助手开放美国所有高尔夫球场（16,845 个），并让它贡献数据、为球员办理签到和举办锦标赛。只需一句提示词，就能构建完整的高尔夫应用。

OpenGolfAPI 是社区所有的公共资源。只需一个免费密钥，你的 Agent 就能读取全球高尔夫数据，并向四项开放标准写入数据。

---

这些标准（完整介绍）

OpenGolfAPI 基于开放、可组合的协议构建——可实现其中一项，也可全部实现：

标准	介绍	用途…
OpenShot	用于测距仪击球数据的 CC0 格式——每种设备（Trackman、GSPro、Garmin、…）都映射到同一套架构。	从任意测距仪／模拟器导入击球数据 → log_shot。
Moments	通用事件导入标准——将任意传感器信号（GPS 轨迹点、挥杆、推杆、球杆、得分、旗杆、状况、在场信息）作为一种灵活的事件处理。	发送你拥有的任何信号 → submit_moment。
OpenJoin	已签名、范围受限且会过期的加入令牌。一个二维码／链接 → 所有兑换令牌的人都会进入同一轮比赛／锦标赛，组成关联群组。	一键邀请一组四人或整个锦标赛 → create_tournament_invite / join_tournament。
OpenGolf ID	可移植的高尔夫身份——“使用 OpenGolf 登录。” 一个假名 player_id 适用于所有应用；差点和历史记录会随球员走遍各处（引擎按 player_id 汇总，因此已认领身份的跨应用记录会自动存在）。	为球员提供整个生态系统通用的身份 → sign_in_with_opengolf。

核心理念： 每一次贡献的击球、事件和比赛轮次，都会让共享公共资源惠及所有人——打造真正的双向数据层。读取免费；贡献数据则是你在标准中赢得一席之地的方式。

---

你的 Agent 能获得什么

• 读取（免费，无需密钥）： 搜索和比较球场 · 完整记分卡（标准杆／差点／码数）· 障碍区 · 实时天气和气候 · 附近地点 · 开球建议。
• 贡献（免费密钥）： log_shot、submit_moment → 写入开放标准 · get_my_shots → 读取自己的数据。
• 身份和锦标赛（免费密钥）： sign_in_with_opengolf（可移植 ID）· create_tournament_invite + join_tournament（举办赛事——差点可选，可采用总杆或净杆计分）。

打造优秀的高尔夫应用只需一个下午，而不是一年。

安装（MCP 客户端配置）

{
  "mcpServers": {
    "opengolfapi": {
      "command": "npx",
      "args": ["-y", "@opengolfapi/mcp-server"],
      "env": {
        "OPENGOLFAPI_KEY": "<free, optional — enables contributing, identity & tournaments>"
      }
    }
  }
}

在 https://courses.opengolfapi.org/api-keys 获取免费的 OPENGOLFAPI_KEY。读取工具无需密钥即可使用。

Claude Desktop： 配置文件为 claude_desktop_config.json（Settings → Developer → Edit Config）。Claude Code： claude mcp add opengolfapi -- npx -y @opengolfapi/mcp-server。不使用密钥？ 删除整个 env 块——所有读取工具都可在没有密钥的情况下使用（请勿将占位符粘贴为密钥）。

可以尝试的第一个提示词： “查找芝加哥附近的高尔夫球场，并告诉我其中难度最高的一个。”

如何选择记分工具： 休闲单场计分 → score_round · 联赛／锦标赛（分数会陆续录入，排名很重要）→ create_competition → record_attempt → finalize_competition · 流式设备／实时应用 → submit_moment。规范领域模型：https://api.opengolfapi.org/api/v1/model

工具

56 个工具：

• search_courses — 按名称、美国州或位置（纬度/经度 + 半径）搜索美国高尔夫球场。返回匹配球场的位置、类型和标准杆数。免费，数据采用 ODbL 许可。
• get_course — 按 ID 获取单个球场的完整详情：记分卡（每洞的标准杆数 + 难度指数）、发球台、位置、联系方式、附近地点。免费。
• get_tees — 获取某个球场的所有发球台组及其评级、坡度和码数。免费。
• get_weather — 获取球场位置的实时天气预报（Weather.gov）。免费。
• get_climate — 获取球场的月度气候常值 + 最佳打球月份。免费。
• get_nearby — 获取球场附近的酒店、餐厅和其他球场。免费。
• log_shot — 向开放的 OpenShot 标准贡献一次高尔夫击球数据（适用于任何发射监测仪）。需要密钥。单位：速度为 mph、角度为 deg、旋转为 rpm、距离为 yds。
• submit_moment — 从任何传感器、可穿戴设备或手机贡献一个 Open Connect 事件。整个传感器数据范围都由此接入——特定类型的数据放入 payload。需要密钥。
• get_my_shots — 按球员或场次读取自己贡献的击球数据。需要密钥。
• get_my_moments — 按球员、场次或类型读取自己贡献的时刻数据（路径记录、挥杆、推杆、状况……）。需要密钥。
• propose_correction — 提议修正球场的 FACT 字段（phone、website、address、architect、year_built、course_name、city、postal_code、course_type）。我们的 AI 会审核（批准／拒绝／需要更多信息）。需要密钥。无法在此处修正几何信息。
• respond_to_review — 回复状态为 needs_info 的修正提案——添加来源或说明，并重新提交审核。需要密钥。
• get_correction — 检查你提交的修正提案的状态／判定（approved | rejected | needs_info | applied）。需要密钥。
• how_to_build — 关于如何基于 OpenGolfAPI 构建，以及如何正确贡献数据的安全指南。在贡献前调用一次。
• get_passport — 免费（公开，无需密钥）。任何高尔夫球手都可分享的记录——显示名称、OpenGolf Member #、打过的球场、轮次、奖杯、推荐人数。在你的应用中展示球员的高尔夫履历。
• record_referral — 记录一位用户推荐另一位用户（一个 REFERRED_BY 关系）——在共享图谱上为你的应用构建邀请循环，并以你的应用为命名空间。需要密钥。
• get_referrals — 获取用户推荐过的高尔夫球手数量（+ 名单）——衡量你的应用病毒式传播循环的指标。需要密钥。
• about — 介绍 OpenGolfAPI 以及如何使用此 MCP 服务。
• request_sign_in_code — 为某人启动“使用 OpenGolf 登录”：向其发送一组 6 位数代码。无需 API 密钥。对方将代码告知你，然后调用 complete_sign_in。
• complete_sign_in — 完成登录：将 6 位数代码换成对方的 OpenGolf ID + 访问令牌（使用 X-OpenGolf-Token 代表对方执行操作）。如果对方是由另一位球员邀请而来，请传入 ref=；这会为推荐记账。
• create_dev_key — 创建与 OpenGolf ID 绑定的开发者 API 密钥（先通过 request_sign_in_code → complete_sign_in 登录）。密钥只返回一次。第一方通道：没有 OpenGolf ID，就没有密钥。
• sign_in_with_opengolf — 根据用户的电子邮件确定性地生成其 OpenGolf ID（sub = ogid_ + sha256(lower(trim(email)))[:16]）——单行，无需重定向。若要获取已验证的会话令牌，请使用 request_sign_in_code → complete_sign_in。
• register_webhook — 为你的域事件注册一个 https URL（HMAC 签名投递，仅限所有者）。需要你的密钥（Authorization: Bearer ogapi_…）。
• create_tournament_invite — 创建可分享的邀请（二维码／链接）；兑换邀请的所有人都会加入同一个赛事／场次。max_uses 用于限制人数（四人组 = 4）。需要密钥。
• join_tournament — 兑换邀请令牌——球员加入群组／赛事。需要密钥。
• list_game_formats — 列出所有 OpenMatch 计分赛制。GROSS 计分免费且无需密钥。
• score_round — 按任意赛制为一轮计分——GROSS，免费，无需密钥。players:[{player_id,holes:{"1":4}}] 或 entries:[{player_id,hole,value}]；holes:[{hole,par,stroke_index?}]。
• plays_like — 有效距离——权威的“打起来相当于”的数值（风／海拔差／温度／海拔），并逐项列出影响因素。免费，无需密钥。搭配 get_conditions 获取实时风况。
• get_conditions — 获取球场的实时天气（温度／风／降水、预报模型、15 分钟缓存）。免费。为 plays_like 提供数据。
• link_dev_key — 在现有密钥上确认你的 OpenGolf ID。先登录；传入访问令牌和密钥。
• list_dev_keys — 列出由你的 OpenGolf ID 拥有的密钥（仅显示前缀）。需要 complete_sign_in 返回的 access_token。
• get_profile — 球员公开的 OpenGolf ID 名片——姓名、头像、链接、偏好设置。免费。
• update_profile — 编辑球员自行声明的个人资料字段（无法设置推导得出的事实）。需要密钥（已认领的球员需要其授权）。
• get_awards — 球员的 OpenAwards——推导得出的奖杯 + 球场护照。需要密钥。
• set_beacon — 广播已获同意且会过期的在线／可用状态信标（present|available|open）。需要密钥。
• find_beacons — 查找活跃的公开信标（寻找同组球友／匹配）。需要密钥。
• record_consent — 记录球员的同意授权（可审计、可撤销）。需要密钥。
• create_competition — 创建一场 Competition（支持任何 OpenMatch 赛制）。需要密钥。
• list_competitions — 列出 Competition（免费）。按组织／球场／状态筛选。
• get_competition — 获取一场 Competition + 实时总杆排名（免费）。
• record_attempt — 记录一次 Attempt（成绩或边赛数值）。幂等。需要密钥。
• finalize_competition — 完成比赛——运行内核并存储总杆 Result。需要密钥。
• broadcast_feed — OpenBroadcast P1——为一场赛事提供一个类型化信息流：按升序 (recorded_at, seq) 排列值得播报的条目（成绩／边赛／金钱／奖项／状况），每条均附带模板播报文案（headline<=60/ticker<=80）。只有已结算记录才会显示金钱信息。取代拼接 moments+results+live_state 的做法。需要密钥 + 场次访问权限（参与者或计算权限）。
• get_handicap — OpenIndex（测试版）——根据真实且经过公证的轮次计算球员的估算差点（每个成绩都在发生时加盖时间戳；任何人都可验证）。非官方，但可证明。使用自己的密钥读取自己的数据免费；player_id 必须采用 ogid_… 格式。
• get_showcase — 球员的公开展示页——其 OpenGolf ID 上的收藏品／记录（og.* 命名空间 + course.*）。免费，无需密钥：传入其 ogid_。已删除标记（已撤销／已过期）的记录会隐藏。可证明的奖杯墙。
• verify_record — 根据 OpenGolf Chain 验证记录／收藏品（这是一个经过签名、哈希链接并锚定到 Bitcoin 的透明日志）。返回哈希 + 是否匹配 + CLIENT-RECOMPUTE 配方（对规范记录计算 sha256）+ 锚点。之后还可继续验证，且全程无需密钥：获取 Merkle 包含证明（GET /chain/anchors/:id/inclusion?hash=），根据 /.well-known/jwks.json 验证检查点的 RS256 签名，并解析 Bitcoin（OpenTimestamps）锚点。免费。不要信任任何人——自行重新计算哈希、检查包含证明并解析 Bitcoin。
• list_webhooks — 列出你的活跃 Webhook 订阅。需要密钥。
• remove_webhook — 按 ID 停用你的某个 Webhook 订阅（保留审计记录）。需要密钥。
• list_orgs — 已验证组织的公开目录（免费）。
• mint_asset — 将 Asset（奖杯／徽章／印章／优惠券／会员资格）铸造到所有者的奖杯柜 + 链上。需要密钥。
• file_claim — 在信任账本中提交 Claim（所有权／证明／身份／记录／修正）。需要密钥。
• list_claims — 列出 Claim（免费）。按申诉人／主体／状态筛选。
• post_beta — 发布某个球场球洞的本地球场知识（“球场攻略”）——为 AI 球童提供素材。需要密钥。
• get_beta — 读取某个球场／球洞的本地球场知识（免费）。
• get_my_chain — 导出你自己的防篡改 OpenGolf Chain + 检查点。需要密钥（读取自己的数据免费）。
• verify_chain — 验证 Chain 导出内容，或遍历公开透明日志（GET /chain/log?subject=），公开且无需密钥——重新计算哈希链接，根据 JWKS 验证每个 RS256 检查点签名，并解析 Bitcoin 锚点；报告篡改情况及位置。全部历史记录（注册表、单球场记录、主记录）均可独立审计——不要信任任何人。

更大的生态系统 — 两个入口

Agent 通过此 MCP 接入；传感器/设备通过 OpenGolf Connect 接入（一个开放连接器，可将任意发射监测仪 — R10、MLM2PRO、Uneekor、SkyTrak、Foresight — 的击球数据流式传输到 POST /v1/shots）。两者都会写入同一个开放共享数据集。→ https://opengolfapi.org/connect

了解更多

• 完整的 AI 编码指南： https://api.opengolfapi.org/llms-full.txt
• 机器规范（OpenAPI 3.1）：https://api.opengolfapi.org/openapi.json
• OpenShot 字段目录：https://api.opengolfapi.org/api/v1/openshot/fields
• Moments 字段目录：https://api.opengolfapi.org/api/v1/moments/fields

采用 MIT 许可。球场数据采用 ODbL 许可。击球数据采用 CC0 许可。

署名（显示或再分发数据时必须注明）： 球场数据 © OpenStreetMap 贡献者（ODbL 1.0），经由 OpenGolfAPI 提供 · 天气数据由 Open-Meteo.com 提供（CC BY 4.0）· 描述来自 Wikipedia（CC BY-SA 4.0）· 联系方式和社交信息来自 Foursquare / Overture（Apache 2.0）。 完整列表：https://opengolfapi.org/attribution