griptonite-mcp

An MCP server for Griptonite, the indoor climbing app. Log attempts and sends, browse routes and grades, and pull your climbing log into any MCP client — Claude Desktop, Claude Code, Cursor, and friends. Built in the same spirit as the popular Garmin MCP servers: a thin, auth-aware wrapper around a fitness backend that has no official public API.

Unofficial. Not affiliated with or endorsed by Griptonite / Cascom Ltd. Reverse-engineered from the app's backend for personal use. Respect Griptonite's Terms of Service and don't hammer their API.

What it can do

Tool	What it does
auth_status	Check whether you're signed in and when the token expires
get_login_url	Get an OAuth login URL to start the sign-in flow
list_venues	Find climbing gyms/venues (optional search)
list_routes	List routes/problems, filter by venue and grade
get_route	Full detail for one route (e.g. an id from an NFC tag)
list_grades	Grade systems Griptonite knows (V-scale, Font, ...)
get_profile	A climber profile (defaults to you)
get_feed	Recent activity feed (your + crew sends)
get_notifications	Your notifications
list_workouts / list_competitions / list_challenges	Training + events
get_gym_rankings	Leaderboard for the gyms you've joined
get_world_rankings	Global ranking across all climbers
get_competition_rankings	Standings for a competition
get_completed_climbs	Every climb you've sent, with tries
get_projects	Climbs you're currently projecting, with tries
get_all_logs	All logged entries (sends + attempts) with tries
log_climb	Log a send / flash / onsight / attempt / project on a route
log_attempt	Shortcut for logging an unsuccessful try
raw_request	Call any API path with your token (discovery / wiring)
list_known_endpoints	Show the confirmed API surface

How it works

Griptonite's backend lives at https://api.griptonite.io and is a Django REST Framework API guarded by OAuth2 (authorization-code, scope appuser). The endpoint names in config.py were confirmed by probing the live API — paths that answer 401 Unauthorized exist; 404s don't. Confirmed groups include routes, grades, venues, feed, venues/rankings (gym leaderboards), profiles/rankings (world), and routes/completed / routes/projects / routes/logs (your climbs). Auth follows the app's own browser login: you sign in once, hand back the code, and the server caches a bearer token (default ~/.griptonite/token.json, gitignored) and refreshes it transparently.

Install

git clone https://github.com/<your-username>/griptonite_mcp.git
cd griptonite_mcp
pip install -e .            # or: pip install -e ".[dev]" for tests

Requires Python 3.10+.

Authenticate (once)

Griptonite has no public API, so there's no API key to paste. Instead you sign in through the browser once and hand the tool the one-time code, exactly like the mobile app does. Run:

griptonite-auth            # or: python -m griptonite_mcp.auth

It prints a login URL. Open it, sign into Griptonite, and copy the code from the redirect back into the terminal. The token is cached (and auto-refreshed) from then on, so you only do this once.

Catching the code (important)

After you log in, Griptonite redirects to https://www.griptonite.io/?code=... — but www.griptonite.io instantly redirects to griptonite.io, and that redirect strips the ?code out of the address bar. That's expected. Grab the code from the Network tab instead:

1. Open your browser's DevTools (F12) and click the Network tab.
2. Tick Preserve log (so redirect entries aren't cleared).
3. Log in via the printed URL.
4. Filter the list by typing code, and click the request named ?code=... (the request to www.griptonite.io). Its Request URL is https://www.griptonite.io/?code=LONGCODE&state=....
   • No such row? Click the authorize request and read its response location header — the code is there.
5. Copy that whole URL (or just the code value) and paste it at the prompt.

The code is single-use and expires in about a minute, so grab it promptly. If you miss it, just re-run griptonite-auth. The tool detects a stripped/empty paste and re-prompts with this reminder.

Why not a localhost redirect? The OAuth client is registered to redirect only to griptonite.io, so the usual "spin up a local server and auto-capture" trick isn't available — hence the one-time manual copy.

Add to Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "griptonite": {
      "command": "python",
      "args": ["-m", "griptonite_mcp"]
    }
  }
}

Then restart Claude Desktop and ask things like "log a V4 flash on route <id>" or "what have I sent at my gym this week?".

Wiring the log endpoint

Reads are fully mapped. The write path for logging a climb (log_climb / log_attempt) is the one piece that couldn't be confirmed without capturing an authenticated request, because the mobile app doesn't expose it publicly. The server's default is POST /routes/log — the singular /routes/log path is confirmed to exist — with the route id sent in the body. That's still a best guess until someone captures the real request; it's trivial to correct:

1. Sign into Griptonite in a browser or proxy the app (Charles / mitmproxy / browser DevTools → Network).
2. Log a climb in the app and find the request it fires.
3. Set the real path and, if needed, adjust the JSON field names:

   export GRIPTONITE_LOG_ENDPOINT="/routes/log"   # or the real path you captured
   

   For field names, tweak the payload dict in log_climb (server.py) or the log_climb method in client.py.
4. Meanwhile you can experiment live with the raw_request tool, e.g. raw_request("POST", "/routes/123/ticks", body={...}).

Example prompts

Once it's wired into your MCP client, try:

• "What have I sent at my home gym this month, and how many tries did each take?"
• "Show my current projects ordered by number of attempts."
• "Where do I rank in my gym right now? And globally?"
• "Log a V4 flash on route <id>."
• "Find blue V3–V5 routes at venue <id> I haven't tried yet."

Configuration

All optional; sensible defaults are baked in. Copy .env.example to .env.

Variable	Default	Purpose
GRIPTONITE_CLIENT_ID	(discovered)	OAuth client id
GRIPTONITE_REDIRECT_URI	https://www.griptonite.io/	OAuth redirect
GRIPTONITE_API_BASE	https://api.griptonite.io	API base URL
GRIPTONITE_TOKEN_PATH	~/.griptonite/token.json	Token cache location
GRIPTONITE_LOG_ENDPOINT	/routes/log	Climb-log write path

Develop

pip install -e ".[dev]"
pytest                              # unit tests (no network / creds needed)
python scripts/discover_endpoints.py   # re-probe the live API surface

Project layout

griptonite_mcp/
  config.py     # env-driven settings + confirmed endpoint constants
  auth.py       # OAuth2 auth-code flow, PKCE, token cache, refresh
  client.py     # async httpx client with 401-refresh-retry
  server.py     # FastMCP server + tool definitions
scripts/
  discover_endpoints.py   # re-map the API surface
tests/
  test_client.py          # request building, error handling, auth URL

Contributing

Issues and PRs welcome — especially confirming API endpoints/payloads. See CONTRIBUTING.md and the CHANGELOG.

Disclaimer

This is an unofficial, community project and is not affiliated with, endorsed by, or supported by Griptonite / Cascom Ltd. It talks to the same backend the official app uses, discovered by observing public network behaviour. Use it for your own data, respect Griptonite's Terms, and don't hammer the API. If Griptonite ships an official API, prefer that.

License

MIT — see LICENSE.