hum MCP server

hum

Every song ever made, free, in a player that feels like a room lit by the album cover.

• Search any song, or paste a Spotify playlist, album or track link (or press ⌘V anywhere).
• Tap a station and it plays forever in that mood.
• Time-synced lyrics, an endless autoplay mix, liked songs, shareable song links.
• No accounts, no keys, no database. Your library lives in your browser.

Playback runs through YouTube's official embedded player, so ads and royalties work the normal way and artists still get paid.

Run it

One command (Node 18+). Starts hum and opens it in your browser:

npx github:anzal1/hum

From a clone:

node server.js

Docker (home server, VPS, NAS):

docker build -t hum . && docker run -p 3737:3737 hum

Put it online for free

hum is a folder of static files plus one small function, so it fits the free tier of Cloudflare Workers: static files are unlimited and 100,000 searches a day are included.

• One click: the Deploy to Cloudflare button on /developers.html, or https://deploy.workers.cloudflare.com/?url=https://github.com/anzal1/hum
• From this folder: npx wrangler deploy

Vercel works too (api/ and vercel.json are ready), but its free plan is for non-commercial use.

Tested: node server.js, npx from a packed tarball, Docker, and Cloudflare's own runtime locally (npx wrangler dev). Every route answered in all four.

Put hum inside your app

One script tag adds a floating player to any page:

<script src="https://YOUR-HUM-HOST/embed.js" data-station="lofi beats"></script>

Then drive it from code: hum.play('Blinding Lights'), hum.station('deep focus'), hum.playlist(spotifyUrl), hum.pause(), hum.next(), hum.volume(60), hum.on('state', fn). Or use the iframe directly: widget.html?station=lofi and postMessage({ hum: 'play', query }). Live demo at /developers.html.

In your coding agent

hum works with any agent that speaks MCP. Your agent is the remote, and the music plays in a hum browser tab. It can play, start a station, import a Spotify link, skip, set the volume, and tell you what is playing, down to the line being sung. Needs Node 18+.

claude mcp add --scope user hum -- npx -y -p github:anzal1/hum hum-mcp

VS Code:

code --add-mcp '{"name":"hum","type":"stdio","command":"npx","args":["-y","-p","github:anzal1/hum","hum-mcp"]}'

Claude Desktop (one-click extension), Cursor (install link), Codex, Gemini CLI, Windsurf, Zed, Copilot CLI, opencode, Cline, Kiro, Amp, Goose and Continue are all in docs/agents.md.

From your terminal

Install once, and the commands start hum and open it for you when needed.

npm i -g github:anzal1/hum

hum play blinding lights       # a song or artist
hum station lofi beats         # an endless mix
hum playlist <spotify link>
hum pause | resume | toggle | next | prev
hum vol 40
hum duck                       # lower the music; hum unduck brings it back
hum now                        # title, artist, progress and the line being sung

hum now --line prints one short line for status bars, and nothing when hum is not running: ♪ Amazing Grace · Judy Collins · I once was lost, but now I am found. It never starts hum and returns in about 30 ms. hum now --json is for scripts.

In tmux (~/.tmux.conf):

set -g status-right '#(hum now --line)'
set -g status-interval 2

In Claude Code (~/.claude/settings.json):

"statusLine": { "type": "command", "command": "hum now --line" }

Anything else can POST to the local remote, which only listens on 127.0.0.1 and only accepts JSON:

curl -X POST localhost:3737/api/remote -H 'content-type: application/json' -d '{"cmd":"station","mood":"lofi"}'

Shortened. The full README is on GitHub.