Skip to main content

kiosktunes-mcp

License: MIT Python 3.11+ MCP Ready al4xdev/kiosktunes-mcp MCP server

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):

  1. 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.
  2. 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.
  3. 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 mpv instance 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-mcp leverages native real-time DSP filters (crystalizer for transient attack/air recovery and extrastereo for spatial headstage expansion).
  • Persistent Agent Memory & User Taste Profiling: Every track played is logged to structured JSONL format. 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 mpv
Debian / Ubuntu: sudo apt install mpv
Fedora: sudo dnf install mpv
macOS: 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/ with 0700/0600 permissions and are never committed or returned through MCP.
  • Safe History & Ratings: history.jsonl and ratings.jsonl track solely music metadata (video_id, title, artists, rating, timestamp), never private credentials. They live in the checkout's logs/ directory, or in $XDG_DATA_HOME/kiosktunes-mcp/ (override with KIOSKTUNES_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.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kiosktunes-mcp 0.1.0
File Size Uploaded Provenance Actions
kiosktunes_mcp-0.1.0.tar.gz 133.6 kB With provenance Details for kiosktunes_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kiosktunes-mcp 0.1.0
File Interpreter ABI Platform Actions
kiosktunes_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for kiosktunes_mcp-0.1.0-py3-none-any.whl

Total release size: 158.0 kB

Release files / kiosktunes_mcp-0.1.0.tar.gz

Download URL kiosktunes_mcp-0.1.0.tar.gz
Size 133.6 kB
Tags Source
SHA-256 checksum
How to use checksums
4f9409945fdcae40b464938d95309f2b0ad56ca42fad0d70bb02772122f29db3
BLAKE2b-256 checksum
How to use checksums
aa59a1f62b3cffdd24d57f9260c11dfdc01faf4c75017eec6f51bb4e7b7dfd84
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 log

Release files / kiosktunes_mcp-0.1.0-py3-none-any.whl

Download URL kiosktunes_mcp-0.1.0-py3-none-any.whl
Size 24.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bb263b7315b951a51a6b504ceb27ebe0cffa3d117b636cc131d6724aa9b476ea
BLAKE2b-256 checksum
How to use checksums
e01724a8ecc5b5c4baf9c9fdfbd783803919d26a17b85ee0730c2d313575deb2
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 log

Security for kiosktunes-mcp 0.1.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.

Select from 2 files

Attestation for kiosktunes_mcp-0.1.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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page