Install on macOS

icuvisor for macOS is distributed as a signed, notarized DMG. The app is a headless .app wrapper around the MCP server binary; AI clients run the binary inside the app bundle.

/Applications/icuvisor.app/Contents/MacOS/icuvisor

The app does not contain credentials. Your intervals.icu API key stays in the macOS Keychain.

Install from the DMG

Download icuvisor_<version>_macos_universal.dmg and SHA256SUMS.txt from the latest GitHub release.
Optional: verify the checksum from the folder where both files were downloaded:
```
shasum -a 256 -c SHA256SUMS.txt --ignore-missing
```
Open the DMG.
Drag icuvisor.app to /Applications or ~/Applications.

Run the binary once to confirm it starts:

/Applications/icuvisor.app/Contents/MacOS/icuvisor version

A properly signed and notarized release should not show the macOS “unidentified developer” warning. If macOS blocks the app, verify the signature before overriding Gatekeeper.

First-run setup

After installing, run:

/Applications/icuvisor.app/Contents/MacOS/icuvisor setup

Setup asks for the intervals.icu API key with masked input, verifies it, stores it in Keychain under service icuvisor and account intervals-icu-api-key, autodetects your athlete ID/timezone, and writes only non-secret fields to the icuvisor config file.

Useful setup flags:

Flag	Use it when
`--config /path/to/config.json`	You want setup to write a non-default config path.
`--force`	You want to overwrite an existing config file without the overwrite prompt.
`--offline`	intervals.icu cannot be reached and you accept skipping verification.

There is no --api-key flag. Setup always asks for the key interactively so the key is not exposed through shell history or MCP client JSON.

Manual Keychain storage remains available for advanced or headless setups:

security add-generic-password -U \
  -s icuvisor \
  -a intervals-icu-api-key \
  -w 'YOUR_INTERVALS_ICU_API_KEY'

Do not put the API key in Claude Desktop, Claude Code, Info.plist, the DMG, or any committed config file.

Verify Gatekeeper and notarization

After dragging the app into Applications, run:

codesign --verify --deep --strict /Applications/icuvisor.app
spctl -a -v /Applications/icuvisor.app
xcrun stapler validate /path/to/icuvisor_<version>_macos_universal.dmg
/Applications/icuvisor.app/Contents/MacOS/icuvisor version

Expected results:

codesign exits 0.
spctl reports the app is accepted and references the Developer ID authority.
stapler validate reports the notarization ticket is valid.
icuvisor version prints the release version without asking for an API key.

Configure an MCP client

Use this command path in the MCP client configuration:

/Applications/icuvisor.app/Contents/MacOS/icuvisor

Keep the API key out of client JSON. Put only non-secret values in the client configuration, such as INTERVALS_ICU_ATHLETE_ID, ICUVISOR_TIMEZONE, ICUVISOR_TRANSPORT, or a --config path. The full list is in the CLI reference.

Uninstall

Quit any MCP clients using icuvisor.
Remove the app:
```
rm -rf /Applications/icuvisor.app
```

Optional: remove the Keychain API key:

security delete-generic-password -s icuvisor -a intervals-icu-api-key

Remove any MCP client config blocks that launch icuvisor.

Optional LaunchAgent for power users

icuvisor does not auto-load a LaunchAgent. Most MCP clients start icuvisor on demand over stdio. If you later add a LaunchAgent for a local workflow, keep it user-scoped, review it before loading, and do not store API keys in the plist.