@leokok/poke-apple-music (npm)

Fast start

npx @leokok/poke-apple-music or npx poke-music runs a readiness check first (macOS, Homebrew as optional, Git, Node/npx, Python 3.10+, Poke login). Missing Homebrew does not block the run.
If something required is missing, it asks y/n and tries, in order:

• Official Homebrew install script when brew is absent and you need Git/Node/Python
• Batch brew install git, node, and/or [email protected] when Homebrew is already available
• Git: xcode-select --install (Command Line Tools), then opening git-scm.com/mac
• Node: fnm, nvm, or asdf if detected, then opening nodejs.org — the CLI also tries to refresh PATH in-process after brew/fnm/nvm
• Python: pyenv if present, then python.org macOS
• npx poke@latest login (you finish in the browser)

Only after everything passes does it clone or update poke-music under ~/.local/share/poke-apple-music/repo (each run fast-forwards with git pull, with a fallback for shallow clones), then pip install -e when HEAD changes, start the MCP server, and run poke tunnel.

If APPLE_MUSIC_MCP_PORT (default 8765) is busy, the CLI picks the next free port and passes it to Python and poke tunnel (opt out with APPLE_MUSIC_STRICT_PORTS=1).

While the bridge runs, Python stderr shows short, useful lines (e.g. what tool ran: search, play, pause) instead of raw MCP noise. For full SDK logs, set POKE_APPLE_MUSIC_RAW_SDK_LOG=1.

Updating: New CLI behavior comes from the npm package version — use npx @leokok/poke-apple-music@latest or npx poke-music@latest (same CLI). New Python/repo changes on GitHub are picked up on the next run via git in that cache (no need to bump npm for repo-only fixes, unless you change the CLI).

Non-interactive / CI: npx @leokok/poke-apple-music --yes or POKE_APPLE_MUSIC_YES=1 (auto-attempts the same fixes without prompts; still needs a TTY for poke login unless already logged in).

Set a custom tunnel label with -n/--name:

npx @leokok/poke-apple-music@latest --name "Work Mac"
# or
npx poke-music@latest -n "Work Mac"

There is no PyPI mcp-applemusic dependency — only this repo + mcp.

Requirements

• git on your PATH
• macOS, Python 3.10+, Node 18+
• npx poke@latest login completed once

Usage

npx @leokok/poke-apple-music
# or (same tool):
npx poke-music

The scoped package installs binaries poke-apple-music and poke-music. The unscoped poke-music package installs poke-music only.

Fork / mirror:

export POKE_APPLE_MUSIC_REPO="https://github.com/you/poke-music.git"
npx @leokok/poke-apple-music

Local development

Use the repository root for development, not the npm package folder:

cd poke-music
npm install
node npm/poke-apple-music/cli.mjs --help
node npm/poke-apple-music/cli.mjs

Cache layout

| Path | Contents | |------|----------| | ~/.local/share/poke-apple-music/repo | Git clone of the repo | | ~/.local/share/poke-apple-music/venv | Python venv | | ~/.local/share/poke-apple-music/installed-git-head | Last pip install -e revision |

After a git pull changes HEAD, the next run reinstalls editable.

CLI options

poke-apple-music --help

• -h, --help show usage
• -v, --version print launcher version
• -y, --yes run non-interactively
• -n, --name <label> set the poke tunnel -n display label

Publish

From poke-music/npm/poke-apple-music:

npm publish --access public

The short name poke-music is a separate package — bump both package.json versions together, then cd ../poke-music && npm publish --access public (or rely on CI).

NO_COLOR

Set NO_COLOR=1 for plain output.

Troubleshooting (what the CLI tries to tell you)

| Situation | What to do | |-----------|------------| | Not macOS | Run on a Mac with the Music app. | | No git | xcode-select --install or brew install git. | | No python3 | Install from python.org or brew install python. Optional: POKE_APPLE_MUSIC_PYTHON. | | Not logged into Poke | npx poke@latest login. | | git pull / update failed | See message; often offline, divergent local edits in the cache, or permission. Wipe cache: rm -rf ~/.local/share/poke-apple-music. | | Clone / pip errors | Check internet; confirm POKE_APPLE_MUSIC_REPO; reset cache with rm -rf ~/.local/share/poke-apple-music. | | Port already in use | The CLI tries the next free port after APPLE_MUSIC_MCP_PORT (default 8765). Use APPLE_MUSIC_STRICT_PORTS=1 to fail instead of auto-bumping. | | MCP crashes on start | Open an issue on GitHub with the Python traceback (run pip install -e from a clone to debug). | | Don’t want prompts | npx @leokok/poke-apple-music --yes or POKE_APPLE_MUSIC_YES=1 (still need Poke login unless already done). | | poke login in a script | Log in once in a normal terminal; --yes won’t complete OAuth for you. |