Skip to main content
Glama
dcarter610

Audio Playback MCP Server

by dcarter610
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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.

  • Get audio file duration (in seconds) when playing files using ffprobe.

  • Stop current playback.

  • Pause playback (saves position); resume continues from that position.

  • Query current status with a position estimate.

  • List audio files hosted locally under AUDIO_ROOT_DIR.

  • Path safety enforcement to prevent leaving the configured root directory.

  • Run as either a local stdio MCP server or a long-running HTTP MCP server.

Related MCP server: Filesystem MCP Server

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 playback settings:

  • DEFAULT_FORMAT: File extension to append when none is provided (default wav).

  • FFPLAY_PATH: Path to the ffplay binary (default ffplay).

  • AUDIO_PLAYBACK_CONFIG: Path to a JSON config file containing any of the above keys.

Optional MCP transport settings:

  • MCP_TRANSPORT: stdio (default) or http.

  • MCP_HTTP_HOST: HTTP bind host for http transport (default 0.0.0.0).

  • MCP_HTTP_PORT: HTTP bind port for http transport (default 8765).

  • MCP_HTTP_PATH: MCP endpoint path for http transport (default /mcp).

  • MCP_DNS_REBINDING_PROTECTION: true/false (default true).

  • MCP_ALLOWED_HOSTS: Comma-separated allow-list of host headers for HTTP mode.

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

Running the server (HTTP, for remote clients)

AUDIO_ROOT_DIR=/path/to/audio \
AUDIO_OUTPUT_DEVICE="Virtual Cable" \
MCP_TRANSPORT=http \
MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_PORT=8765 \
MCP_HTTP_PATH=/mcp \
python -m audio_playback_server

In HTTP mode, the server stays running and accepts MCP requests at http://<host>:<port><path> (for example http://192.168.1.10:8765/mcp).

Remote access notes (Windows host + Raspberry Pi client)

  1. Bind to 0.0.0.0 so the server listens on your LAN interface.

  2. Allow inbound TCP on MCP_HTTP_PORT in Windows Defender Firewall.

  3. If MCP host-header checks block requests, set MCP_ALLOWED_HOSTS to include the hostname/IP your client uses, or disable checks with MCP_DNS_REBINDING_PROTECTION=false for trusted networks only.

  4. Configure your Raspberry Pi MCP client/Openclaw to call your Windows machine at http://<windows-lan-ip>:8765/mcp.

Tool schema

The audio_playback tool accepts the following JSON input:

  • action: play, stop, pause, resume, status, or list_files (required)

  • filename: Relative path under AUDIO_ROOT_DIR (required for play)

  • start_offset_ms: Start offset in milliseconds (default 0)

  • list_limit: Maximum number of files returned when action=list_files (default 200)

Responses always include success, message, and a state object with status, current_file, started_at_ms, and position_estimate_ms. When playing a file, the response also includes duration_seconds (float) in the state object, indicating the total duration of the audio file in seconds. The duration is also included in the message text for convenience. For list_files, responses also include a files payload containing root_dir, count, limit, and files entries (filename, size_bytes).

Available Tools

1 tool
audio_playbackB

Control playback of local audio files for automated testing. Audio is played via a virtual audio output device that is routed into the Android emulator's microphone. Use this to simulate a human speaking into the mic by playing prerecorded files.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYes
filenameNo
start_offset_msNo
list_limitNo

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool controls playback for testing via a virtual device, which hints at non-destructive and system-specific behavior, but lacks details on permissions, rate limits, error handling, or what 'status' and 'list_files' actions return. For a tool with 4 parameters and no annotations, this is a significant gap in behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose and usage without waste. Every sentence earns its place by introducing the tool's function and its specific testing application, making it easy to scan and understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, no annotations, no output schema), the description is incomplete. It covers the high-level purpose and testing context but lacks details on behavioral traits, parameter meanings, and return values, which are crucial for an agent to use the tool effectively in an automated testing scenario.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter documentation. It mentions 'playing prerecorded files', which relates to the 'filename' parameter, but does not explain the semantics of 'action' enum values (e.g., what 'status' returns), 'start_offset_ms', or 'list_limit'. With 4 parameters and low coverage, the description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('control playback') and resources ('local audio files'), and distinguishes its unique context ('for automated testing', 'via a virtual audio output device', 'routed into the Android emulator's microphone', 'to simulate a human speaking into the mic'). It goes beyond the tool name by explaining the testing scenario and routing mechanism.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context ('for automated testing', 'to simulate a human speaking into the mic by playing prerecorded files'), which gives a clear when-to-use scenario. However, it does not provide explicit alternatives, exclusions, or prerequisites, and there are no sibling tools mentioned for comparison, limiting guidance to implicit context only.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.1.0
    • First observedaudio_playback
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap between tools, as there are no other tools to compare it to. The single tool has a clear and distinct purpose focused on audio playback for testing.

Naming Consistency5/5

Since there is only one tool, naming consistency is inherently perfect—there are no other tool names to be inconsistent with. The tool name 'audio_playback' follows a clear verb_noun pattern.

Tool Count2/5

A single tool is too few for a server with the purpose of controlling audio playback for automated testing, as it suggests a very limited scope that may not cover essential operations like pausing, stopping, or managing audio files. This is borderline for the apparent domain.

Completeness2/5

The tool surface is severely incomplete for audio playback control; it only offers playback without supporting basic operations such as pause, stop, volume control, or file management. This will likely cause agent failures in handling more complex testing scenarios.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dcarter610/MCP-Virtual-Audio-Player'

If you have feedback or need assistance with the MCP directory API, please join our Discord server