Audio Playback MCP Server
This repository provides an MCP server named audio-playback-server that exposes a single audio_playback tool. The tool lets an MCP client start, stop, and inspect playback of local audio files routed through a configurable virtual audio output device.
Features
- Play audio files from a configurable root directory using
ffplay. - Stop current playback.
- Query current status with a position estimate.
- Path safety enforcement to prevent leaving the configured root directory.
Configuration
The server reads configuration from environment variables and an optional JSON file. Environment variables take precedence over JSON values.
Required:
AUDIO_ROOT_DIR: Root directory containing allowed audio files.AUDIO_OUTPUT_DEVICE: Identifier of the virtual output device.
Optional:
DEFAULT_FORMAT: File extension to append when none is provided (defaultwav).FFPLAY_PATH: Path to theffplaybinary (defaultffplay).AUDIO_PLAYBACK_CONFIG: Path to a JSON config file containing any of the above keys.
An example config file is provided at config/audio_playback_config.example.json.
Installation
python -m venv .venv
source .venv/bin/activate
pip install -e .
Running the server (stdio)
AUDIO_ROOT_DIR=/path/to/audio \\
AUDIO_OUTPUT_DEVICE="Virtual Cable" \\
python -m audio_playback_server
The server listens on stdio following the MCP specification. Register the audio_playback tool with your MCP host using the tool schema defined in audio_playback_server/server.py.
Tool schema
The audio_playback tool accepts the following JSON input:
action:play,stop, orstatus(required)filename: Relative path underAUDIO_ROOT_DIR(required forplay)loop: Loop playback until stopped (defaultfalse)start_offset_ms: Start offset in milliseconds (default0)
Responses always include success, message, and a state object with status, current_file, started_at_ms, and position_estimate_ms.