mcp-volumio by ilboud - MCP Server

Volumio MCP Server

A Model Context Protocol (MCP) server for controlling Volumio music player via its WebSocket API. This server enables AI agents and applications to control music playback, manage playlists, browse libraries, and interact with all Volumio features.

Key Features

✨ 39 Comprehensive Tools - Complete control over Volumio with prefix-namespaced tools (volumio_*) 📖 Detailed Documentation - Every tool has comprehensive docstrings with usage examples and error handling 📄 Pagination Support - Efficient handling of large datasets in search, browse, and queue operations 🔍 Smart Error Handling - Categorized error codes (CONNECTION, TIMEOUT, VALIDATION, etc.) with detailed context 🐳 Docker Ready - Production-ready containerized deployment with environment-based configuration 🔒 Secure by Default - Non-root container user, HTTPS support, input validation with Pydantic 📡 Stateless HTTP - FastMCP with HTTP Streamable protocol for efficient communication 🔌 WebSocket Client - Persistent Socket.IO connection to Volumio with auto-reconnection

Tool Categories

Playback Control

Play, pause, stop playback
Skip to next track, go to previous track
Seek to specific playback positions
Query current player state and track information

Volume Management

Set volume to specific level (0-100%)
Increase/decrease volume
Mute/unmute audio

Playback Modes

Enable/disable shuffle (random) mode
Enable/disable repeat mode
Get/set repeat single track

Queue Management

Add tracks to queue
Remove tracks from queue by position
Move queue items to different positions
Retrieve current play queue with pagination support (limit/offset)

Playlist Management

Create new playlists
Delete existing playlists
Add tracks to playlists
Remove tracks from playlists
Play entire playlists
Enqueue playlist tracks

Favorites Management

Add tracks to favorites
Remove tracks from favorites

Music Library

Search music library with pagination support (minimum 3 characters recommended)
Browse library by URI with pagination support
Get available music sources (USB, NAS, Spotify, Web Radio, etc.)
Get available library filters (Artists, Albums, Genres, etc.)

Multiroom Audio

Retrieve all connected multiroom devices
Get device status and information

Sleep & Alarms

Get/set sleep timer
Get configured alarms
Add new alarms
Remove alarms

Architecture

┌─────────────────────────────────────────┐
│         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              │
└─────────────────────────────────────────┘

Project Structure

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

Requirements

Docker & Docker Compose (for containerized deployment)
Python 3.11+ (for local development)
Volumio instance running and accessible (default: localhost:3000)
Network connectivity between MCP server and Volumio

Installation & Deployment

Quick Start with Docker (Recommended)

Clone the repository:

git clone <repository-url>
cd mcp-volumio

Configure Volumio connection:

cp .env.example .env

Edit .env and set your Volumio instance details:

# 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

Build and start the Docker container:

docker compose build
docker compose up -d

Verify it's running:

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

The MCP server will be available at http://localhost:8000.

Docker Deployment Options

HTTP Deployment (Development & Local Use)

Using docker compose:

# 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

Passing Volumio hostname via command line:

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

# Or edit .env file and restart
docker compose restart

Manual Docker run (without 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

Endpoints:

MCP Server: http://localhost:8000
MCP Streamable: http://localhost:8000/mcp

HTTPS Deployment (Production with Nginx)

Generate SSL certificates:

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

Update .env for your domain:

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

Start with HTTPS:

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

Endpoints:

MCP Server: https://your-domain.com
MCP Streamable: https://your-domain.com/mcp

Local Development Setup

Install Python dependencies:
```
uv sync
```
Create .env file:
```
cp .env.example .env
```
Run the server:
```
uv run python -m mcp_volumio
```

The server will start on http://localhost:8000 and attempt to connect to Volumio at localhost:3000.

Configuration

Environment Variables

# 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

Volumio Network Access

Make sure your Volumio instance is accessible:

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

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

Usage

MCP Tools

The server exposes 39 tools for controlling Volumio. All tools are prefixed with volumio_ to prevent naming conflicts when used alongside other MCP servers.

Examples:

Play Current Track

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

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

Set Volume

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

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

Search Music Library

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

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

Add to Playlist

# 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 Reference

All tools are prefixed with volumio_ to prevent naming conflicts in multi-server environments.

Playback Control

Tool	Parameters	Description
`volumio_play`	None	Start playback
`volumio_pause`	None	Pause playback
`volumio_stop`	None	Stop playback
`volumio_next`	None	Skip to next track
`volumio_previous`	None	Play previous track
`volumio_seek`	`position: int`	Seek to position (seconds)
`volumio_get_player_state`	None	Get current player state*

Volume Control

Tool	Parameters	Description
`volumio_set_volume`	`volume: int (0-100)`	Set volume level
`volumio_increase_volume`	None	Increase volume
`volumio_decrease_volume`	None	Decrease volume
`volumio_mute`	None	Mute audio
`volumio_unmute`	None	Unmute audio

Playback Modes

Tool	Parameters	Description
`volumio_set_random`	`enabled: bool`	Enable/disable shuffle
`volumio_set_repeat`	`enabled: bool`	Enable/disable repeat
`volumio_set_repeat_single`	`enabled: bool`	Enable/disable repeat single track

Queue Management

Tool	Parameters	Description
`volumio_add_to_queue`	`uri: str`, `service?: str`	Add track to queue
`volumio_remove_from_queue`	`position: int`	Remove by position
`volumio_move_queue_item`	`from_position: int`, `to_position: int`	Move item
`volumio_get_queue`	`limit?: int (1-200, default: 50)`, `offset?: int (default: 0)`	Get current queue with pagination*

Playlist Management

Tool	Parameters	Description
`volumio_create_playlist`	`name: str`, `service?: str`	Create new playlist
`volumio_create_spotify_playlist`	`name: str`	Create Spotify playlist
`volumio_delete_playlist`	`name: str`	Delete playlist
`volumio_add_to_playlist`	`playlist_name: str`, `uri: str`, `service: str`	Add track
`volumio_remove_from_playlist`	`playlist_name: str`, `uri: str`	Remove track
`volumio_play_playlist`	`name: str`	Play entire playlist
`volumio_enqueue_playlist`	`name: str`	Add playlist to queue
`volumio_get_playlists`	None	List all playlists*

Music Library

Tool	Parameters	Description
`volumio_search`	`query: str`, `limit?: int (1-200, default: 50)`, `offset?: int (default: 0)`	Search library with pagination*
`volumio_browse_library`	`uri: str`, `limit?: int (1-500, default: 100)`, `offset?: int (default: 0)`	Browse by URI with pagination*
`volumio_get_browse_sources`	None	List music sources
`volumio_get_browse_filters`	None	List available filters

Favorites

Tool	Parameters	Description
`volumio_add_to_favorites`	`uri: str`, `title: str`, `service: str`	Add to favorites
`volumio_remove_from_favorites`	`uri: str`, `service: str`	Remove from favorites

Multiroom

Tool	Parameters	Description
`volumio_get_multiroom_devices`	None	Get multiroom devices*

Alarms & Sleep

Tool	Parameters	Description
`volumio_get_sleep_timer`	None	Get sleep timer status
`volumio_set_sleep_timer`	`enabled: bool`, `time?: str`	Set sleep timer
`volumio_get_alarms`	None	Get all alarms
`volumio_add_alarm`	`time: str (HH:MM)`, `playlist_uri: str`	Add alarm
`volumio_remove_alarm`	`alarm_id: int`	Remove alarm

*Tools marked with asterisk return validated Pydantic models with structured data.

Monitoring & Management

Container Monitoring

# 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

Testing Connection

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

Stop/Restart Server

# Stop
docker-compose down

# Restart
docker-compose up -d

# Stop with data cleanup
docker-compose down -v

Troubleshooting

Server Won't Start

Check Docker:

docker --version
docker-compose --version

Check Volumio connectivity:

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

View logs:
```
docker-compose logs mcp-server
```

Can't Connect to Volumio

Verify Volumio is running:

ping <VOLUMIO_HOST>
nc -zv <VOLUMIO_HOST> 3000

Update .env with correct Volumio host:

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

Restart server:
```
docker-compose restart
```

HTTPS Certificate Issues

Regenerate certificates:
```
./scripts/generate-ssl.sh
```

Check certificate validity:

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

Ensure certificates are readable:

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

Development

Running Tests

uv run pytest -v

Code Quality

# Format code
uv run black src/

# Lint code
uv run ruff check src/

# Type checking
uv run mypy src/

Building Locally

# Install dependencies
uv sync

# Run directly
uv run python -m mcp_volumio

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

API Documentation Reference

For detailed information about Volumio's WebSocket API, see:

Performance Considerations

Stateless Operation: The server is stateless and can be scaled horizontally
Connection Pooling: Socket.io client automatically handles reconnections
Timeout Management: Default 5-second timeout for WebSocket commands
Streaming Support: HTTP Streamable protocol for efficient long-polling

Security Considerations

Network Access: Restrict access to trusted networks only
SSL/TLS: Use HTTPS in production (see SSL certificate setup)
Authentication: Implement authentication at reverse proxy level if needed
Input Validation: All input parameters are validated with Pydantic
Container Security: Server runs as non-root user inside container

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please ensure:

Code follows black/ruff style guidelines
All tests pass
Documentation is updated
Commit messages are descriptive

Support

For issues, feature requests, or questions:

Check the troubleshooting section
Review Volumio API documentation
Check application logs: docker-compose logs mcp-server
Open an issue with detailed information

Changelog

v0.5.0 (Latest - Phase 4: Error Handling)

Enhanced Error Handling: Comprehensive error categorization with 6 error code types
- CONNECTION_ERROR, TIMEOUT_ERROR, VALIDATION_ERROR, VOLUMIO_ERROR, INTERNAL_ERROR, PARAMETER_ERROR
Standardized Error Responses: All tools return consistent error format with optional details
Improved Logging: Added logging to all 33 command tools (previously missing)
Better Debugging: Error responses include context (event name, timeout, parameters)
Separated Error Types: TimeoutError, ValidationError, and ConnectionError handled distinctly
Fixed Docker build issues (uv.lock, README.md, .dockerignore)
Updated docker-compose.yml to modern syntax (removed obsolete version attribute)

v0.4.0 (Phase 3: Pagination Support)

Pagination for Large Datasets: Added pagination support to 3 high-volume tools
- volumio_get_queue: limit (1-200, default: 50), offset parameters
- volumio_search: limit (1-200, default: 50), offset parameters
- volumio_browse_library: limit (1-500, default: 100), offset parameters
Pagination Metadata: All paginated responses include total, offset, limit, returned, has_more
Per-Category Pagination: Search and browse support pagination within each result category
Client-Side Pagination: Efficient result slicing since Volumio doesn't support server-side pagination
Fixed default parameter handling with Annotated[type, Field()] pattern

v0.3.0 (Phase 2: Comprehensive Documentation)

Added detailed docstrings to all 39 tools following MCP best practices
Tool Documentation Includes:
- Clear descriptions of functionality and purpose
- Complete parameter documentation with types, ranges, and examples
- Detailed return value documentation with response structures
- Usage examples (when to use / when not to use)
- Comprehensive error handling documentation
- Notes about Volumio-specific behavior and limitations
Enhanced AI agent usability with context-rich tool descriptions

v0.2.0 (Phase 1: MCP Best Practices)

BREAKING: Renamed all 39 tools with volumio_ prefix (e.g., play → volumio_play)
BREAKING: Server name changed from "Volumio" to "volumio_mcp"
Added comprehensive tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
Improved multi-server compatibility
Updated all documentation with new tool names

v0.1.0 (Initial Release)

Initial implementation of Volumio MCP Server
39 tools for music control and management
Docker deployment with HTTP and HTTPS support
FastMCP with stateless HTTP transport
Socket.IO WebSocket client for Volumio communication
Full API documentation