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

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, simp_mcp leverages native real-time DSP filters (crystalizer for transient attack/air recovery and extrastereo for spatial headstage expansion).

• Persistent Agent Memory: Every track played is logged to structured JSONL format so future AI agents can query your listening history (get_listening_history) to curate tailored playlists for deep work or hackathons.

• Lazy Turnkey MCP: Instant startup with zero background overhead until an audio command is actually dispatched.

Related MCP server: ytm-mcp

🚀 Key Features

• 20 MCP Tools for search, playback, queue management, volume, seek, radio recommendations, lyrics, and history.

• 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

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

Clone the repository and install dependencies using uv:

git clone https://github.com/al4xdev/kiosktunes-mcp.git
cd kiosktunes-mcp
uv sync

Direct CLI Usage

# Search and play a track immediately
uv run simp-mcp music play "Perturbator Future Club"

# Playback controls
uv run simp-mcp music pause
uv run simp-mcp music resume
uv run simp-mcp music next
uv run simp-mcp music volume 85

# Inspect live audio codec, bitrate, and queue
uv run simp-mcp music status
uv run simp-mcp music queue

# View playback history logged for agents
uv run simp-mcp history

🤖 MCP Agent Integration (Claude, Cursor, OpenCode, DSH)

simp_mcp operates as a standard stdio Model Context Protocol (MCP) server.

Automatic Setup

Print ready-to-paste configurations for any tool:

uv run simp-mcp mcp --config

Or write turnkey configuration into your current project:

uv run simp-mcp mcp --setup

Manual Configuration Snippets

1. Claude Code CLI

claude mcp add music uv -- run --directory /absolute/path/to/simp_mcp simp-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": "uv",
      "args": ["run", "--directory", "/absolute/path/to/simp_mcp", "simp-mcp"]
    }
  }
}

🎵 Complete MCP Tool Catalog

🎧 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/rt-music/ with 0700/0600 permissions and are never committed or returned through MCP.

• Safe History: logs/history.jsonl tracks solely music metadata (video_id, title, artists, timestamp), never private credentials.

🧪 Testing & Verification

Run the comprehensive unit test suite:

uv run pytest -q

Current test suite: 42 passed tests covering IPC socket handling, CLI argument parsing, audio history, and authentication sanitization.

📄 License

MIT License. See LICENSE for details.