Open Golf Handicap MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Open Golf Handicap MCP What's my golf handicap?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 loginThe 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 |
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-mcpClaude 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 rosterYour 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 |
| One golfer's Handicap Index, with its effective date and when it was retrieved |
| Find golfers by first/last name and US state to get their GHIN number |
| Up to 100 golfers at once; each one succeeds or fails on its own |
| Course handicap from an index plus course rating, slope and par (9 or 18 holes) |
| Add golfers to your roster (bulk import asks you to confirm first) |
| Manage your roster |
| Re-check everyone (or selected golfers) and show what changed |
| Changes this tool has observed over a period |
| Export your roster as JSON / delete it (asks you to confirm) |
| Connection details and limits / end the GHIN session |
| 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
loginResults 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 |
Assistant only shows demo golfers | No login was found when the AI app started. Run |
| Run |
Sign-in fails | Check your username and password in the GHIN app first. |
| You reached this tool's daily limit, or GHIN asked it to slow down. |
macOS asks to allow access to the Keychain item | Click Always Allow so the server can read your saved login |
Client can't find | Desktop apps may not see your shell's PATH (common with nvm). Use the full path from |
| 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 itTests 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 toolsdelete_golfer_rosterADestructive
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_providerADestructive
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_rosterBRead-onlyIdempotent
Export the private roster and retained change history as portable JSON.
Inputs: no named parameters. Returns: ok, data, error
get_connection_statusARead-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_handicapBRead-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_handicapARead-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_changesBRead-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_historyBRead-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_handicapsARead-onlyIdempotent
Retrieve indexes for up to 100 numbers; deduplicate, batch, and return individual failures.
Inputs: ghinNumbers (required), forceRefresh. Returns: ok, data, error
get_recent_scoresBRead-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_golfersARead-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_golferADestructive
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_golfersARead-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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
Enables AI assistants to retrieve event data and execute event management operations in Nunify.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Lets Claude, ChatGPT, and Muse read and update your beckett tasks, notes, calendar, and lists.
Access your Callin.io AI phone agents, call history and transcripts from any AI assistant.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables 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 npm4-
- FlicenseNot gradedqualityDmaintenanceEnables AI applications to retrieve GitHub repository information, manage issues, and monitor workflow statuses through the GitHub REST API.-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to retrieve and discuss personal fitness activities, training splits, heart-rate zones, and daily health metrics from a Garmin Connect account.MIT
- AlicenseNot gradedqualityBmaintenanceConnects 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 npmMIT