使用说明

Volumeo MCP服务器

一种模型上下文协议（MCP）服务器，用于通过其WebSocket API控制Volumio音乐播放器。此服务器使AI代理和应用程序能够控制音乐播放、管理播放列表、浏览库以及与所有Volumeo功能进行交互。

主要特点

✨ 39综合工具 -使用前缀命名空间工具完全控制Volumeo(volumio_*) 📖 详细文件 -每个工具都有全面的文档字符串，其中包含使用示例和错误处理 📄 分页支持 -在搜索、浏览和队列操作中高效处理大型数据集 🔍 智能错误处理 -带有详细上下文的分类错误代码（连接、超时、验证等） 🐳 Docker就绪 -基于环境配置的生产就绪容器化部署 🔒 缺省巩固安全 -非根容器用户，HTTPS支持，使用Pydantic进行输入验证 📡 无状态HTTP -FastMCP采用HTTP流协议，实现高效通信 🔌 WebSocket客户端 -持久套接字。IO连接到Volumeio并自动重新连接

工具类别

回放控制

播放、暂停、停止播放
跳到下一首曲目，跳到上一首曲目
寻找特定的播放位置
查询当前玩家状态和轨迹信息

卷管理

将音量设置为特定水平（0-100%）
增加/减少音量
静音/取消静音音频

播放模式

启用/禁用随机洗牌模式
启用/禁用重复模式
获取/设置重复单曲

队列管理

将曲目添加到队列
按位置从队列中删除轨迹
将队列项目移动到不同位置
使用分页支持（限制/偏移）检索当前播放队列

播放列表管理

创建新播放列表
删除现有播放列表
将曲目添加到播放列表
从播放列表中删除曲目
播放整个播放列表
Enqueue播放列表曲目

收藏夹管理

将曲目添加到收藏夹
从收藏夹中删除曲目

音乐库

搜索支持分页的音乐库（建议至少3个字符）
通过支持分页的URI浏览库
获取可用的音乐源（USB、NAS、Spotify、网络广播等）
获取可用的库过滤器（艺术家、专辑、流派等）

多房间音频

检索所有连接的多房间设备
获取设备状态和信息

睡眠和闹钟

获取/设置睡眠定时器
获取已配置的警报
添加新警报
删除警报

建筑

┌─────────────────────────────────────────┐
│         AI Application / Agent          │
└────────────────┬────────────────────────┘
                 │
                 │ HTTP/Streamable
                 ▼
┌─────────────────────────────────────────┐
│      Volumio MCP Server (FastAPI)       │
│  ├─ /health (Health checks)             │
│  ├─ /info (Server info)                 │
│  ├─ /mcp (MCP endpoint - streaming)     │
│  └─ Socket.io Client Manager            │
└────────────────┬────────────────────────┘
                 │
                 │ WebSocket (Socket.io)
                 ▼
┌─────────────────────────────────────────┐
│    Volumio Backend (WebSocket API)      │
│    Default: localhost:3000              │
└─────────────────────────────────────────┘

项目结构

mcp-volumio/
├── src/mcp_volumio/
│   ├── __init__.py              # Package initialization
│   ├── __main__.py              # Entry point
│   └── server.py                # Main MCP server implementation
├── pyproject.toml               # Python project configuration
├── Dockerfile                   # Docker container definition
├── docker-compose.yml           # HTTP deployment orchestration
├── docker-compose.https.yml     # HTTPS deployment orchestration
├── .env.example                 # Environment variables template
├── .dockerignore                # Docker ignore patterns
├── nginx/
│   ├── nginx.conf               # HTTP Nginx configuration
│   └── nginx-https.conf         # HTTPS Nginx configuration
├── ssl/
│   ├── README.md               # SSL certificate generation guide
│   └── (certificates - not in git)
├── scripts/
│   ├── start.sh                # Quick start script
│   ├── generate-ssl.sh         # SSL certificate generation
│   └── test-connection.py      # Connection test script
└── README.md                    # This file

需求

Docker和Docker Compose（用于容器化部署）
Python 3.11+（用于本地开发）
Volumeio实例正在运行且可访问（默认值：localhost:3000）
MCP服务器和Volumeio之间的网络连接

安装和部署

Docker快速入门（推荐）

克隆存储库：

git clone <repository-url>
cd mcp-volumio

配置Volumeo连接：

cp .env.example .env

编辑 .env 并设置您的Volumeo实例详细信息：

# For Volumio on the same machine
VOLUMIO_HOST=localhost
VOLUMIO_PORT=3000

# For Volumio on a different machine (recommended)
VOLUMIO_HOST=192.168.1.100    # Replace with your Volumio's IP address
VOLUMIO_PORT=3000

# Optional: Change MCP server port (default: 8000)
MCP_PORT=8000
LOG_LEVEL=info

构建并启动Docker容器：

docker compose build
docker compose up -d

验证它是否正在运行：

docker ps --filter "name=mcp-volumio-server"
docker logs mcp-volumio-server

MCP服务器将在 http://localhost:8000.

Docker部署选项

HTTP部署（开发和本地使用）

使用docker编写：

# Start container
docker compose up -d

# View logs
docker logs mcp-volumio-server -f

# Stop container
docker compose down

# Rebuild and restart
docker compose up -d --build

通过命令行传递Volumeo主机名：

# Using environment variable
VOLUMIO_HOST=192.168.1.100 docker compose up -d

# Or edit .env file and restart
docker compose restart

手动运行Docker（不使用compose）：

docker build -t mcp-volumio:latest .

docker run -d \
  --name mcp-volumio-server \
  -p 8000:8000 \
  -e VOLUMIO_HOST=192.168.1.100 \
  -e VOLUMIO_PORT=3000 \
  -e LOG_LEVEL=info \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  mcp-volumio:latest

终点：

MCP服务器： http://localhost:8000
MCP可流式传输： http://localhost:8000/mcp

HTTPS部署（使用Nginx的生产环境）

生成SSL证书：

chmod +x scripts/generate-ssl.sh
./scripts/generate-ssl.sh

为您的域更新.env：

VOLUMIO_HOST=192.168.1.100  # Your Volumio IP
DOMAIN_NAME=your-domain.com
HTTPS_PORT=443
HTTP_PORT=80

从HTTPS开始：

docker compose -f docker-compose.https.yml up -d

终点：

MCP服务器： https://your-domain.com
MCP可流式传输： https://your-domain.com/mcp

地方发展设置

安装Python依赖项：
```
uv sync
```
创建.env文件：
```
cp .env.example .env
```
运行服务器：
```
uv run python -m mcp_volumio
```

服务器将于启动 http://localhost:8000 并尝试连接到Volumio localhost:3000.

配置

环境变量

# MCP Server
MCP_HOST=0.0.0.0          # Server host (container)
MCP_PORT=8000             # Server port

# Volumio Connection
VOLUMIO_HOST=localhost    # Volumio instance host
VOLUMIO_PORT=3000         # Volumio instance WebSocket port

# Logging
LOG_LEVEL=info            # Logging level (debug, info, warning, error)

# Nginx/HTTPS
HTTP_PORT=80              # HTTP port
HTTPS_PORT=443            # HTTPS port
DOMAIN_NAME=localhost     # Domain for SSL certificates

Volumeo网络接入

确保您的Volumeo实例可访问：

# Test connectivity
curl http://<VOLUMIO_HOST>:3000/api/v1/getstate

# Check if WebSocket is available
nc -zv <VOLUMIO_HOST> 3000

用法

MCP工具

服务器公开了39个用于控制Volumeo的工具。所有工具都以前缀 volumio_ 以防止与其他MCP服务器一起使用时发生命名冲突。

示例：

播放当前曲目

# Request
{
  "name": "volumio_play",
  "arguments": {}
}

# Response
{"status": "success", "message": "Play command sent"}

设置音量

# Request
{
  "name": "volumio_set_volume",
  "arguments": {"volume": 75}
}

# Response
{"status": "success", "message": "Volume set to 75%"}

搜索音乐库

# Request
{
  "name": "volumio_search",
  "arguments": {"query": "Beatles"}
}

# Response
{"status": "success", "data": { ... }}

添加到播放列表

# Request
{
  "name": "volumio_add_to_playlist",
  "arguments": {
    "playlist_name": "My Favorites",
    "uri": "music-library/artist/The Beatles/Let It Be",
    "service": "mpd"
  }
}

# Response
{"status": "success", "message": "Added track to playlist 'My Favorites' (service: mpd)"}

API 参考

所有工具都以前缀 volumio_ 以防止多服务器环境中的命名冲突。

回放控制

工具	参数	说明
`volumio_play`	无	开始播放
`volumio_pause`	无	暂停播放
`volumio_stop`	无	停止播放
`volumio_next`	无	跳到下一首曲目
`volumio_previous`	无	播放上一首曲目
`volumio_seek`	`position: int`	定位（秒）
`volumio_get_player_state`	无	获取当前玩家状态*

音量控制

工具	参数	说明
`volumio_set_volume`	`volume: int (0-100)`	设置音量级别
`volumio_increase_volume`	无	增加音量
`volumio_decrease_volume`	无	减少音量
`volumio_mute`	无	将音频静音
`volumio_unmute`	无	取消音频静音

播放模式

工具	参数	说明
`volumio_set_random`	`enabled: bool`	启用/禁用随机播放
`volumio_set_repeat`	`enabled: bool`	启用/禁用重复
`volumio_set_repeat_single`	`enabled: bool`	启用/禁用重复单轨

队列管理

工具	参数	说明
`volumio_add_to_queue`	`uri: str`, `service?: str`	将曲目添加到队列
`volumio_remove_from_queue`	`position: int`	按位置删除
`volumio_move_queue_item`	`from_position: int`, `to_position: int`	移动项目
`volumio_get_queue`	`limit?: int (1-200, default: 50)`, `offset?: int (default: 0)`	使用分页获取当前队列*

播放列表管理

工具	参数	说明
`volumio_create_playlist`	`name: str`, `service?: str`	创建新播放列表
`volumio_create_spotify_playlist`	`name: str`	创建Spotify播放列表
`volumio_delete_playlist`	`name: str`	删除播放列表
`volumio_add_to_playlist`	`playlist_name: str`, `uri: str`, `service: str`	添加曲目
`volumio_remove_from_playlist`	`playlist_name: str`, `uri: str`	移除轨道
`volumio_play_playlist`	`name: str`	播放整个播放列表
`volumio_enqueue_playlist`	`name: str`	将播放列表添加到队列
`volumio_get_playlists`	无	列出所有播放列表*

音乐库

工具	参数	说明
`volumio_search`	`query: str`, `limit?: int (1-200, default: 50)`, `offset?: int (default: 0)`	带分页的搜索库*
`volumio_browse_library`	`uri: str`, `limit?: int (1-500, default: 100)`, `offset?: int (default: 0)`	按带分页的URI浏览*
`volumio_get_browse_sources`	无	列出音乐源
`volumio_get_browse_filters`	无	列出可用筛选器

收藏夹

工具	参数	说明
`volumio_add_to_favorites`	`uri: str`, `title: str`, `service: str`	添加到收藏夹
`volumio_remove_from_favorites`	`uri: str`, `service: str`	从收藏夹中删除

多房间

工具	参数	说明
`volumio_get_multiroom_devices`	无	获取多房间设备*

闹钟和睡眠

工具	参数	说明
`volumio_get_sleep_timer`	无	获取睡眠定时器状态
`volumio_set_sleep_timer`	`enabled: bool`, `time?: str`	设置睡眠定时器
`volumio_get_alarms`	无	获取所有警报
`volumio_add_alarm`	`time: str (HH:MM)`, `playlist_uri: str`	添加警报
`volumio_remove_alarm`	`alarm_id: int`	解除报警

*标有星号的工具返回具有结构化数据的已验证Pydantic模型。

监控与管理

集装箱监控

# Check container status
docker ps --filter "name=mcp-volumio-server"

# View logs
docker logs mcp-volumio-server -f

# View recent logs
docker logs mcp-volumio-server --tail 50

测试连接

chmod +x scripts/test-connection.py
python scripts/test-connection.py

停止/重新启动服务器

# Stop
docker-compose down

# Restart
docker-compose up -d

# Stop with data cleanup
docker-compose down -v

故障排除

服务器无法启动

检查Docker：

docker --version
docker-compose --version

检查Volumeo连接：

curl http://<VOLUMIO_HOST>:3000/api/v1/getstate

查看日志：
```
docker-compose logs mcp-server
```

无法连接到Volumeo

验证Volumeio是否正在运行：

ping <VOLUMIO_HOST>
nc -zv <VOLUMIO_HOST> 3000

使用正确的Volumeo主机更新.env：

VOLUMIO_HOST=<your-volumio-ip>
VOLUMIO_PORT=3000

重新启动服务器：
```
docker-compose restart
```

HTTPS证书问题

重新生成证书：
```
./scripts/generate-ssl.sh
```

检查证书有效性：

openssl x509 -in ssl/cert.pem -text -noout

确保证书可读：

ls -la ssl/
chmod 644 ssl/cert.pem ssl/key.pem

发展

运行测试

uv run pytest -v

代码质量

# Format code
uv run black src/

# Lint code
uv run ruff check src/

# Type checking
uv run mypy src/

在当地建设

# Install dependencies
uv sync

# Run directly
uv run python -m mcp_volumio

# Build Docker image
docker build -t mcp-volumio:local .

API文件参考

有关Volumio的WebSocket API的详细信息，请参阅：

性能注意事项

无状态操作：服务器是无状态的，可以水平扩展
连接池：Socket.io客户端自动处理重新连接
超时管理：WebSocket命令的默认5秒超时
流媒体支持：用于高效长轮询的HTTP流协议

安全考虑

网络接入：仅限制访问受信任的网络
SSL/TLS：在生产环境中使用HTTPS（请参阅SSL证书设置）
认证：如果需要，在反向代理级别实施身份验证
输入验证：所有输入参数均使用Pydantic进行验证
集装箱安全：服务器在容器内以非root用户身份运行

许可证

有关详细信息，请参阅LICENSE文件。

贡献

欢迎投稿！请确保：

代码遵循黑色/褶边风格指南
所有测试均通过
文档已更新
提交消息是描述性的

支持

对于问题、功能请求或疑问：

检查故障排除部分
查看Volumio API文档
检查应用程序日志： docker-compose logs mcp-server
打开一个包含详细信息的问题

更新日志

v0.5.0（最新版本-第4阶段：错误处理）

增强的错误处理：具有6种错误代码类型的全面错误分类
- CONNECTION_ERROR, TIMEOUT_ERROR, VALIDATION_ERROR, VOLUMIO_ERROR, INTERNAL_ERROR, PARAMETER_ERROR
标准化错误响应：所有工具返回一致的错误格式和可选的详细信息
改进日志记录：为所有33个命令工具添加了日志记录（以前缺失）
更好的调试：错误响应包括上下文（事件名称、超时、参数）
分离的错误类型：TimeoutError、ValidationError和ConnectionError的处理方式不同
修复了Docker构建问题（uv.lock、README.md、.dockerinore）
将docker-compose.yml更新为现代语法（删除了过时的版本属性）

v0.4.0（第3阶段：分页支持）

大型数据集的分页：为3个高容量工具添加了分页支持
- volumio_get_queue：限制（1-200，默认值：50），偏移参数
- volumio_search：限制（1-200，默认值：50），偏移参数
- volumio_browse_library：限制（1-500，默认值：100），偏移参数
分页元数据：所有分页响应包括总计、偏移、限制、返回、has_more
按类别分页：搜索和浏览支持在每个结果类别中分页
客户端分页：高效的结果切片，因为Volumeio不支持服务器端分页
修复了带注释[type，Field（）]模式的默认参数处理

v0.3.0（第2阶段：综合文档）

根据MCP最佳实践，为所有39个工具添加了详细的文档字符串
工具文档包括:
- 功能和目的的清晰描述
- 完整的参数文档，包括类型、范围和示例
- 带有响应结构的详细返回值文档
- 使用示例（何时使用/何时不使用）
- 全面的错误处理文档
- 关于Volumeo特定行为和限制的说明
通过上下文丰富的工具描述增强了AI代理的可用性

v0.2.0（第1阶段：MCP最佳实践）

突发：将所有39个工具重命名为 volumio_ 前缀（例如。， play → volumio_play)
突发：服务器名称从“Volumio”更改为“Volumio_mcp”
添加了全面的工具注释（readOnlyHint、destructiveHint、幂等Hint、openWorldHint）
改进了多服务器兼容性
用新的工具名称更新了所有文档

v0.1.0（初始版本）

Volumeo MCP服务器的初步实现
39个音乐控制和管理工具
支持HTTP和HTTPS的Docker部署
具有无状态HTTP传输的FastMCP
插座。用于Volumeio通信的IO WebSocket客户端
API完整文档

使用说明

Volumeo MCP服务器

主要特点

工具类别

回放控制

卷管理

播放模式

队列管理

播放列表管理

收藏夹管理

音乐库

多房间音频

睡眠和闹钟

建筑

项目结构

需求

安装和部署

Docker快速入门（推荐）

Docker部署选项

HTTP部署（开发和本地使用）

HTTPS部署（使用Nginx的生产环境）

地方发展设置

配置

环境变量

Volumeo网络接入

用法

MCP工具

播放当前曲目

设置音量

搜索音乐库

添加到播放列表

API 参考

回放控制

音量控制

播放模式

队列管理

播放列表管理

音乐库

收藏夹

多房间

闹钟和睡眠

监控与管理

集装箱监控

测试连接

停止/重新启动服务器

故障排除

服务器无法启动

无法连接到Volumeo

HTTPS证书问题

发展

运行测试

代码质量

在当地建设

API文件参考

性能注意事项

安全考虑

许可证

贡献

支持

更新日志

v0.5.0（最新版本-第4阶段：错误处理）

v0.4.0（第3阶段：分页支持）

v0.3.0（第2阶段：综合文档）

v0.2.0（第1阶段：MCP最佳实践）

v0.1.0（初始版本）

相关 MCP

Apple音乐控制服务

Spotify音乐控制服务

YouTube MCP服务器

音乐播放控制服务

YouTube音乐控制服务器

Spotify控制服务