Audio Playback MCP Server

音频播放MCP服务器

此存储库提供了一个名为的MCP服务器 audio-playback-server 这暴露了一个 audio_playback 工具。该工具允许MCP客户端启动、停止和检查通过可配置的虚拟音频输出设备路由的本地音频文件的播放。

特性

• 使用播放可配置根目录中的音频文件 ffplay.
• 使用获取播放文件时的音频文件持续时间（秒） ffprobe.
• 停止当前播放。
• 暂停播放（保存位置）；简历从那个位置继续。
• 使用职位估计查询当前状态。
• 列出本地托管的音频文件 AUDIO_ROOT_DIR.
• 路径安全强制，以防止离开配置的根目录。
• 作为本地stdio MCP服务器或长时间运行的HTTP MCP服务器运行。

配置

服务器从环境变量和可选的JSON文件中读取配置。环境变量优先于JSON值。

必修的：

• AUDIO_ROOT_DIR：包含允许的音频文件的根目录。
• AUDIO_OUTPUT_DEVICE：虚拟输出设备的标识符。

可选播放设置：

• DEFAULT_FORMAT：未提供文件扩展名时附加的文件扩展名（默认 wav).
• FFPLAY_PATH：通往 ffplay 二进制（默认 ffplay).
• AUDIO_PLAYBACK_CONFIG：包含上述任何键的JSON配置文件的路径。

可选MCP传输设置：

• MCP_TRANSPORT: stdio （默认）或 http.
• MCP_HTTP_HOST：HTTP绑定主机 http 运输（默认 0.0.0.0).
• MCP_HTTP_PORT：的HTTP绑定端口 http 运输（默认 8765).
• MCP_HTTP_PATH：MCP端点路径 http 运输（默认 /mcp).
• MCP_DNS_REBINDING_PROTECTION: true/false （默认值 true).
• MCP_ALLOWED_HOSTS：逗号分隔的HTTP模式主机标头允许列表。

示例配置文件提供在 config/audio_playback_config.example.json.

安装

python -m venv .venv
source .venv/bin/activate
pip install -e .

运行服务器（stdio）

AUDIO_ROOT_DIR=/path/to/audio \
AUDIO_OUTPUT_DEVICE="Virtual Cable" \
python -m audio_playback_server

运行服务器（HTTP，用于远程客户端）

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

在HTTP模式下，服务器保持运行并接受MCP请求 `http://:

（例如 http://192.168.1.10:8765/mcp`).

远程访问说明（Windows主机+Raspberry Pi客户端）

1. 绑定到 0.0.0.0 所以服务器会监听你的局域网接口。
2. 允许启用入站TCP MCP_HTTP_PORT 在Windows Defender防火墙中。
3. 如果MCP主机标头检查块请求，则设置 MCP_ALLOWED_HOSTS 包含客户端使用的主机名/IP，或禁用与 MCP_DNS_REBINDING_PROTECTION=false 仅适用于可信网络。
4. 配置您的Raspberry Pi MCP客户端/Openclaw以调用您的Windows计算机 http://:8765/mcp.

工具架构

这 audio_playback 该工具接受以下JSON输入：

• action: play, stop, pause, resume, status，或 list_files （必填）
• filename：相对路径 AUDIO_ROOT_DIR （需要 play)
• start_offset_ms：开始偏移量（毫秒）（默认值 0)
• list_limit：返回的最大文件数 action=list_files （默认值 200)

响应总是包括 success, message和a state 带有对象 status, current_file, started_at_ms，以及 position_estimate_ms。播放文件时，响应还包括 duration_seconds （浮动）在 state 对象，表示音频文件的总持续时间（秒）。持续时间也包括在 message 为了方便起见，请使用文本。对于 list_files，回复还包括 files 有效载荷包含 root_dir, count, limit，以及 files 条目(filename, size_bytes).