kiosktunes-mcp
A standalone, zero-bloat music server and Model Context Protocol (MCP) tool suite designed for developers, autonomous AI agents, and TTY/terminal power users.
Stream YouTube Music audio directly to your local hardware using mpv and yt-dlp, with persistent daemon playback, real-time DSP audio enhancement, automatic taste/history logging for AI agents, and zero GPU/VRAM overhead.
💡 Why This Exists: The Problem & The Solution
When working in low-resource environments (e.g., pure TTY sessions, heavy build/compilation jobs like Kotlin/Rust, or training/running local LLMs and Diffusion models on your GPU):
- Desktop/Browser Bloat: Opening YouTube or a desktop streaming client consumes 800 MB to 2 GB of RAM and reserves precious GPU/VRAM for window compositing and video decoding.
- Disconnected Chats & Process Lifecycles: Typical terminal audio scripts run inside your shell session; when an AI agent chat restarts, reconnects, or finishes, the music stops and the queue is lost.
- Subpar Audio Compression: Streaming lossy web audio without hardware equalization often sounds dull, muddy, or lacks dynamic presence.
The Solution:
- Detached Daemon Architecture: A dedicated
mpvinstance runs in background with a Unix IPC socket (mpv.sock). Closing the agent, disconnecting chats, or switching TTYs never interrupts playback. - Real-Time DSP Hardware Enhancement (Zero VRAM): Rather than slow, heavy AI upscaling (AudioSR) that consumes gigabytes of VRAM,
kiosktunes-mcpleverages native real-time DSP filters (crystalizerfor transient attack/air recovery andextrastereofor spatial headstage expansion). - Persistent Agent Memory & User Taste Profiling: Every track played is logged to structured
JSONLformat. Users and agents can classify and rate songs on a 0–5 star scale (rate_music,get_user_ratings) to curate personalized playlists and discover new music based on verified favorites. - Compact & Batch-First for LLMs: High-leverage, polymorphic tools accept single items or lists. Search runs multi-query lookups concurrently, playback defaults to non-interrupting
enqueue=True, and pruned compact metadata cuts LLM context token usage by over 80%. - Lazy Turnkey MCP: Instant startup with zero background overhead until an audio command is actually dispatched.
🚀 Key Features
- 21 MCP Tools for search, playback, batch queueing, volume, seek, radio recommendations, lyrics, history, and taste ratings.
- Small-Model Optimized: Polymorphic single/batch operations without tool bloat; compact search outputs keep LLM context clean.
- Strict Opus Stream Selection: Prefers raw 48 kHz Opus (
format 251) without lossy-to-lossy MP3 re-encoding. - Zero VRAM footprint: Keeps your GPU 100% free for LLMs (Ollama/vLLM) and Diffusion models (Flux/SDXL).
- CLI & Agent Friendly: Use it via conversational AI agents (Claude Code, Cursor, OpenCode, DSH) or standard terminal CLI.
- Safe Authentication: Clean isolation for optional YouTube Music session import without exposing tokens or cookies to chat context.
📦 System Requirements & Dependencies
kiosktunes-mcp is designed to be lightweight by delegating playback to standard system tools rather than embedding bulky multimedia frameworks.
Prerequisites
| Component | Purpose | Installation |
|---|---|---|
| Python 3.11+ | Application runtime | Managed via uv (curl -LsSf https://astral.sh/uv/install.sh | sh) |
| mpv | Detached background audio engine | Arch Linux: sudo pacman -S mpvDebian / Ubuntu: sudo apt install mpvFedora: sudo dnf install mpvmacOS: brew install mpv |
| FFmpeg | DSP audio filters (crystalizer, extrastereo) |
Usually bundled with mpv on modern distros |
| Deno (Recommended) | Fast headless JS runtime for YouTube signature deciphering | curl -fsSL https://deno.land/install.sh | sh |
Note on PipeWire / PulseAudio: The player outputs audio through your active user audio server. If running in a raw headless TTY, ensure your user audio daemon (PipeWire/PulseAudio) is running (
systemctl --user status pipewire).
🛠️ Quick Start & Installation
No clone required — install the published package with your Python tool manager:
uv tool install kiosktunes-mcp # or: pipx install kiosktunes-mcp
Prefer zero install? uvx kiosktunes-mcp music play "Perturbator Future Club" runs it straight from an ephemeral environment.
Only mpv (and its bundled FFmpeg filters) must be installed at the system level; PyPI provides Python code, not native binaries.
Direct CLI Usage
# Search and play a track immediately
kiosktunes-mcp music play "Perturbator Future Club"
# Playback controls
kiosktunes-mcp music pause
kiosktunes-mcp music resume
kiosktunes-mcp music next
kiosktunes-mcp music volume 85
# Inspect live audio codec, bitrate, and queue
kiosktunes-mcp music status
kiosktunes-mcp music queue
# Rate/like the currently playing track (0.0 to 5.0 score)
kiosktunes-mcp music rate --score 5.0 --notes "Favorite track"
# View rated tracks and listening history
kiosktunes-mcp music ratings --min 4.0
kiosktunes-mcp history
From Source (Development)
git clone https://github.com/al4xdev/kiosktunes-mcp.git
cd kiosktunes-mcp
uv sync
uv run kiosktunes-mcp music play "Daft Punk Get Lucky"
🤖 MCP Agent Integration (Claude, Cursor, OpenCode, DSH)
kiosktunes-mcp operates as a standard stdio Model Context Protocol (MCP) server.
Automatic Setup
Print ready-to-paste configurations for any tool:
kiosktunes-mcp mcp --config
Or write turnkey configuration into your current project:
kiosktunes-mcp mcp --setup
Both commands emit uv run --directory <checkout> inside the repository and uvx kiosktunes-mcp for installed copies.
Community Registries & 1-Click Install
- Glama.ai: View verified server health, tool schemas, and connect directly.
- Smithery CLI: Install directly into your client of choice without manual configuration:
npx -y @smithery/cli install @al4xdev/kiosktunes-mcp --client claude
Manual Configuration Snippets
1. Claude Code CLI
claude mcp add music uvx -- kiosktunes-mcp
2. OpenCode / Cursor / DSH / Claude Desktop (mcp.json)
Add the following to your agent configuration (.agents/mcp.json or ~/.dsh/mcp.json):
{
"mcpServers": {
"music": {
"command": "uvx",
"args": ["kiosktunes-mcp"]
}
}
}
From a source checkout, use "command": "uv" with "args": ["run", "--directory", "/absolute/path/to/kiosktunes-mcp", "kiosktunes-mcp"] instead.
🎵 Complete MCP Tool Catalog
| Category | Tools | Description |
|---|---|---|
| Discovery | search_music, get_album, get_artist, get_radio, get_lyrics |
Search songs/albums/artists (compact by default, concurrent multi-query support) and fetch related tracks or lyrics |
| Playback | play_music, playback_status, control_playback, seek_music, set_volume, set_repeat |
Real-time audio control; non-interrupting enqueue=True by default, batch video_id queuing |
| Queue | get_queue, edit_queue, enqueue_playlist |
Manage, reorder, or batch remove playlist tracks |
| Intelligence | get_listening_history, rate_music, get_user_ratings |
Log listening activity, rate tracks (0–5), and retrieve taste profiles for AI-powered discovery |
| Auth & Lifecycle | auth_status, import_simpmusic_auth, shutdown_player |
Safe session inspection and graceful mpv shutdown |
🎧 Real-Time Audio DSP & Quality Specs
The player configures mpv to bypass arbitrary transcoders and apply real-time Psychoacoustic DSP:
--ytdl-format="bestaudio[acodec=opus]/bestaudio[acodec=m4a]/bestaudio/best"
--af="lavfi=[crystalizer=i=2.0],lavfi=[extrastereo=m=1.1]"
- Bitstream: Direct Opus stream at 48 kHz (~128-160 kbps VBR).
crystalizer=i=2.0: Re-expands dynamic transients and high-frequency harmonics dampened by lossy codecs.extrastereo=m=1.1: Subtle 10% stereo widening designed specifically for headphones.- Resource Usage: < 1% single CPU core, 0 MB VRAM.
🔒 Security & Privacy Boundary
- No Credentials in Diagnostics: All MCP tool errors and status returns sanitize tokens, cookies, and signed URLs.
- Local Isolation: Credentials (if imported) remain in
$XDG_CONFIG_HOME/kiosktunes-mcp/with0700/0600permissions and are never committed or returned through MCP. - Safe History & Ratings:
history.jsonlandratings.jsonltrack solely music metadata (video_id,title,artists,rating,timestamp), never private credentials. They live in the checkout'slogs/directory, or in$XDG_DATA_HOME/kiosktunes-mcp/(override withKIOSKTUNES_DATA_DIR) for installed copies.
🧪 Testing & Verification
Run the comprehensive unit test suite:
uv run pytest -q
Current test suite: 58 passed tests covering concurrent multi-query search, compact output, batch playback, reverse queue removal, rating profiles, audio DSP, and authentication sanitization.
📄 License
MIT License. See LICENSE for details.
Metadata
Release files for kiosktunes-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kiosktunes_mcp-0.2.0.tar.gz | 136.7 kB | With provenance | Details for kiosktunes_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kiosktunes_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for kiosktunes_mcp-0.2.0-py3-none-any.whl |
Total release size: 163.5 kB
Release files / kiosktunes_mcp-0.2.0.tar.gz
| Download URL | kiosktunes_mcp-0.2.0.tar.gz |
|---|---|
| Size | 136.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dd3744f4f06c99ac10e1dd98ab1ed1b241ef0230fb2cd2017173965a071feed2
|
|
BLAKE2b-256 checksum How to use checksums |
1ce1fd8a6a51945188a6ba9b35d3b742a184e479dc0fe42ac95928717fa05cc3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / kiosktunes_mcp-0.2.0-py3-none-any.whl
| Download URL | kiosktunes_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 26.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
29e81b4d635e8649cf529de7696934cfd58f77ca4291d775bd4e2df48a511d34
|
|
BLAKE2b-256 checksum How to use checksums |
d790cca6bd5d84000ffd021f0407a50bc7051c4e606606df012ad248c20f601e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for kiosktunes-mcp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kiosktunes_mcp-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.