Skip to main content
Glama
Open Golf Handicap MCP

Open Golf Handicap MCP

Open Golf Handicap MCP

Ask your AI assistant for golf handicaps. This is an MCP server that signs in to GHIN with your own account and looks up Handicap Indexes for you and your friends. It also keeps a private, encrypted roster of the golfers you play with and calculates course handicaps.

WARNING

Unofficial. Not affiliated with, endorsed by or supported by the USGA or GHIN.

  • This tool signs in to GHIN the way the GHIN mobile app does, using the GHIN username and password you enter. The GHIN Terms of Service restrict automated access. Using this tool may violate them, and GHIN could suspend or close your account.

  • It only reads handicap data. It never posts scores or changes anything in GHIN.

  • Only look up golfers you have a reason to look up, and respect their privacy.

  • You use it entirely at your own risk. The software is provided "as is", without warranty of any kind (see LICENSE). The authors are not responsible for any consequences of its use, including account suspension.

The first time you connect, the setup program shows this notice and asks you to type I UNDERSTAND.

USGA, GHIN and Handicap Index are trademarks of the United States Golf Association. They are used here only to describe what the software is compatible with.

What it can do

  • "What's my handicap?" / "Look up handicaps for 1234567 and 7654321"

  • "Find Alex Smith in North Carolina and add them to my roster"

  • "Save Alex, GHIN 1234567, to my roster" (or paste a screenshot of a list and let the assistant read it)

  • "Refresh everyone on my roster and tell me who changed"

  • "What's Alex's course handicap at a 71.4 / 131 course, par 72?"

Your GHIN password stays on your computer. It's typed into a private terminal window, never into the AI chat, and the AI never sees it.

Related MCP server: MCP GitHub Automation Server

Requirements

  • macOS, Linux or Windows 10/11

  • Node.js 22 or later

  • An MCP client that runs local servers, such as Claude Desktop, Claude Code, Cursor or Codex

  • Your own GHIN account (username/email and password)

Setup (about two minutes)

1. Sign in once

Open a terminal (Terminal on macOS, PowerShell or Windows Terminal on Windows) and run:

npx -y -p open-golf-handicap-mcp open-golf-handicap-setup login

The first time, it shows the notice above and asks you to type I UNDERSTAND. Then it asks for your GHIN username and password (nothing appears as you type them). Your GHIN number comes from GHIN's sign-in, so you don't need to enter it. It checks them with GHIN once, then saves them in your computer's own password store:

System

Where your login is kept

macOS

Keychain

Windows

Encrypted with your Windows account (Data Protection API)

Linux

Your desktop keyring via secret-tool (or see Linux without a keyring)

You don't need to do this again unless your GHIN password changes.

2. Add it to your AI app

Claude Code:

claude mcp add golf-handicap -- npx -y open-golf-handicap-mcp

Claude Desktop: Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "golf-handicap": {
      "command": "npx",
      "args": ["-y", "open-golf-handicap-mcp"]
    }
  }
}

On Windows use "command": "cmd" and "args": ["/c", "npx", "-y", "open-golf-handicap-mcp"]. Restart Claude Desktop after saving. Cursor uses the same mcpServers format in ~/.cursor/mcp.json.

Codex (~/.codex/config.toml):

[mcp_servers.golf_handicap]
command = "npx"
args = ["-y", "open-golf-handicap-mcp"]

3. Ask

"What's my golf handicap?" The server signs in to GHIN by itself the first time a lookup needs it. There's nothing to keep open.

Other commands

npx -y -p open-golf-handicap-mcp open-golf-handicap-setup status        # what's saved, lookups left today
npx -y -p open-golf-handicap-mcp open-golf-handicap-setup logout        # remove your GHIN login (keeps your roster)
npx -y -p open-golf-handicap-mcp open-golf-handicap-setup logout --all  # also forget your roster

Your roster and settings live in ~/.open-golf-handicap (%USERPROFILE%\.open-golf-handicap on Windows). Add --profile DIR to any command (and to the server's args) to use a different folder.

Tools

Tool

What it does

get_golfer_handicap

One golfer's Handicap Index, with its effective date and when it was retrieved

search_golfers

Find golfers by first/last name and US state to get their GHIN number

get_multiple_handicaps

Up to 100 golfers at once; each one succeeds or fails on its own

get_course_handicap

Course handicap from an index plus course rating, slope and par (9 or 18 holes)

save_golfer / save_multiple_golfers

Add golfers to your roster (bulk import asks you to confirm first)

get_saved_golfers / update_saved_golfer / remove_saved_golfer

Manage your roster

refresh_saved_handicaps

Re-check everyone (or selected golfers) and show what changed

get_handicap_changes

Changes this tool has observed over a period

export_golfer_roster / delete_golfer_roster

Export your roster as JSON / delete it (asks you to confirm)

get_connection_status / disconnect_provider

Connection details and limits / end the GHIN session

get_handicap_history / get_recent_scores

Not available with GHIN (demo data only)

Plus indexes are shown with a + (for example +0.9). A missing value is reported as unavailable, never as zero.

Built-in limits

This tool deliberately keeps GHIN traffic low. These limits are this project's own choices, not quotas published by GHIN:

  • At least 2 seconds between requests to GHIN

  • At most 60 GHIN lookup requests per session, and 200 lookups plus 10 sign-ins per rolling 24 hours (one lookup request can cover up to 100 golfers)

  • A failed request is retried at most once

  • If GHIN says "slow down" (HTTP 429), lookups pause for as long as GHIN asks (at least 1 minute, or 15 minutes if it doesn't say), even across sessions

  • If GHIN refuses access (HTTP 403), lookups stop until you sign in again with login

  • Results are cached for 1 hour. Nothing refreshes in the background.

Privacy and security

  • Your GHIN password is typed only into the setup command in your terminal. It is never passed through the AI chat, command-line arguments, environment variables or the AI app's config.

  • It is stored in your operating system's password store (see the table above), together with the key that encrypts your roster.

  • Your roster is encrypted on disk (AES-256-GCM) in a folder only your user account can access.

  • Nothing is sent anywhere except GHIN's own servers (and Google's Firebase service, which the GHIN app uses during sign-in). There is no telemetry and no central server.

  • The AI app you use does see the handicap results and roster names you ask about. Its provider's privacy policy applies to that.

More detail is in SECURITY.md and docs/security-model.md.

Try it without a GHIN account

Without a saved login, the server runs in demo mode with synthetic golfers 900000001 through 900000005. Add --demo to the server's args to force demo mode. Demo data is fake; never use it for a real competition.

Troubleshooting

Problem

Fix

Assistant says GHIN sign-in is needed

Run the login command in a terminal, then restart your AI app

Assistant only shows demo golfers

No login was found when the AI app started. Run login, then restart the AI app

PRIVATE_INPUT_REQUIRED

Run login in a real terminal window (Terminal, iTerm, Windows Terminal), not inside an AI tool or an IDE output pane

Sign-in fails

Check your username and password in the GHIN app first.

RATE_LIMITED

You reached this tool's daily limit, or GHIN asked it to slow down. status shows when it resets

macOS asks to allow access to the Keychain item

Click Always Allow so the server can read your saved login

Client can't find npx

Desktop apps may not see your shell's PATH (common with nvm). Use the full path from which npx (macOS/Linux) or where npx (Windows) as the command

PROFILE_INVALID

The profile folder's permissions were changed or it is a link. Use a folder inside your home directory that only you can access

Linux without a keyring

On a server or minimal desktop without secret-tool, set OGH_CREDENTIAL_STORE=file for both the login command and the server (in your AI app's config env). The login is then kept in ~/.open-golf-handicap/credentials.json, readable only by your account.

Development

npm ci --ignore-scripts
npm run check          # typecheck, tests, build
npm run test:package   # install the packed package in a clean directory and smoke-test it

Tests never contact GHIN. They use synthetic credentials and intercepted HTTP responses. See CONTRIBUTING.md.

This project uses the MIT-licensed @spicygolf/ghin client (see THIRD_PARTY_NOTICES.md).

License

MIT. The license covers this code only. It does not grant any right to access GHIN.

Available Tools

17 tools
delete_golfer_rosterA
Destructive

Preview deletion first. After explicit user confirmation, submit the returned token and confirmed=true. Clears all roster and history content plus cache; an encrypted empty revision record remains. Backups must be removed separately by their owner.

Inputs: confirmed, confirmationToken. Returns: ok, data, error

disconnect_providerA
Destructive

Disconnect this owner's provider session, purge lookup cache, and report whether provider credentials remain stored. Remote revocation depends on the provider. Revoke MCP grants separately at their issuer.

Inputs: no named parameters. Returns: ok, data, error

export_golfer_rosterB
Read-onlyIdempotent

Export the private roster and retained change history as portable JSON.

Inputs: no named parameters. Returns: ok, data, error

get_connection_statusA
Read-onlyIdempotent

Inspect MCP identity, provider authentication, credential-storage status, expiry, capabilities and limitations; never returns credentials. yourGhinNumber is the user's own GHIN number if they saved one at login: use it for questions like "what's my handicap"; if it is null, ask the user for their number.

Inputs: no named parameters. Returns: ok, data, error

get_course_handicapB
Read-onlyIdempotent

Educational local Course Handicap calculation for supplied 9- or 18-hole ratings. Use negative numbers for plus indexes. Does not apply a Playing Handicap allowance.

Inputs: par (required), holes (required), slope (required), courseRating (required), +1 more. Returns: ok, data, error

get_golfer_handicapA
Read-onlyIdempotent

Retrieve one Handicap Index by GHIN number, with source and synthetic provenance. Omit ghinNumber to look up the signed-in user's own handicap (for "what's my handicap"). Unknown or unavailable golfers return errors. Force still obeys request limits.

Inputs: ghinNumber, forceRefresh. Returns: ok, data, error

get_handicap_changesB
Read-onlyIdempotent

Read recorded observations for an inclusive UTC interval, up to the retained 5000 changes.

Inputs: since (required), until. Returns: ok, data, error

get_handicap_historyB
Read-onlyIdempotent

Handicap history. Demo mode only: not available with a GHIN login (fails with UNSUPPORTED). Do not offer it to GHIN users.

Inputs: ghinNumber (required), limit. Returns: ok, data, error

get_multiple_handicapsA
Read-onlyIdempotent

Retrieve indexes for up to 100 numbers; deduplicate, batch, and return individual failures.

Inputs: ghinNumbers (required), forceRefresh. Returns: ok, data, error

get_recent_scoresB
Read-onlyIdempotent

Recent scores. Demo mode only: not available with a GHIN login (fails with UNSUPPORTED). Do not offer it to GHIN users.

Inputs: ghinNumber (required), limit. Returns: ok, data, error

get_saved_golfersA
Read-onlyIdempotent

Retrieve the authenticated user’s private roster, optionally search names or nicknames.

Inputs: query. Returns: ok, data, error

refresh_saved_handicapsB

Refresh all or selected saved golfers. Cached reads keep their original retrieval time. Preserve last valid handicaps on failure and report changes individually.

Inputs: ids, forceRefresh. Returns: ok, data, error

remove_saved_golferA
Destructive

Remove one golfer and associated change history from your roster.

Inputs: id (required). Returns: ok, data, error

save_golferA

Add one explicitly requested golfer to the private roster. Use save_multiple_golfers for screenshot imports.

Inputs: name (required), ghinNumber (required), notes, nickname. Returns: ok, data, error

save_multiple_golfersA

Preview image-derived or text records first with confirmed=false. Show the returned records and duplicates to the user. Only after explicit confirmation resend identical records, confirmed=true, and the returned token (valid 5 minutes). No images are stored.

Inputs: golfers (required), confirmed, confirmationToken. Returns: ok, data, error

search_golfersA
Read-onlyIdempotent

Find golfers by name to get their GHIN number and current index. Needs a first name; add a last name and a 2-letter US state code (e.g. NC) to narrow it. Returns up to 25 active US golfers. Several people often share a name: show the matches (name, club, state) and let the user pick before saving anyone to the roster.

Inputs: firstName (required), state, lastName. Returns: ok, data, error

update_saved_golferC

Update a saved name, GHIN number, nickname, or notes. Changing GHIN clears the old handicap and its change history.

Inputs: id (required), patch (required). Returns: ok, data, error

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools target clearly distinct resources or actions: single vs batch handicap lookup, roster CRUD, search, export, and connection management are well separated. The only mild ambiguity is between handicap history, recent scores, and recorded handicap changes, but the descriptions clarify different data sources and modes.

    Naming Consistency5/5

    Tool names consistently use snake_case verb_noun patterns such as get_golfer_handicap, save_multiple_golfers, update_saved_golfer, and export_golfer_roster. The convention is predictable throughout, including connection tools like get_connection_status and disconnect_provider.

    Tool Count4/5

    17 tools is slightly above the typical ideal range, but the surface spans lookup, roster management, history, export, deletion, and connection status, so most tools have a clear role. It is not excessively bloated for the domain, though a few lifecycle tools could potentially be consolidated.

    Completeness4/5

    The server covers the main lifecycle well: search, single and batch handicap lookup, save/update/remove saved golfers, refresh, change history, export, and roster deletion. Minor gaps remain around provider connection/login, since only status and disconnect are exposed, and course handicap calculation explicitly omits playing-handicap allowance.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to access and query Garmin Connect health and fitness data, including sleep, HRV, training load, and activities, with an optional coaching plugin for personalized training plans.
      9 npm
      4
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to retrieve and discuss personal fitness activities, training splits, heart-rate zones, and daily health metrics from a Garmin Connect account.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects AI agents to Garmin Connect so they can read fitness data (activities, sleep, steps, heart rate, weight, workouts, profile) and schedule or manage Garmin Calendar workouts with an explicit confirmation flow.
      51 npm
      MIT