SoundTouchMCP

An MCP server for controlling Bose SoundTouch speakers via the SoundTouch WebServices API.

Features

• Power on / off (standby)
• Volume up, down, and set to a specific level
• List and play presets by name or number
• Bluetooth pairing mode
• Device info and listing
• Network discovery — Zeroconf (_soundtouch._tcp.local.) and subnet scan

Prerequisites

• .NET 8.0 SDK
• One or more Bose SoundTouch devices on your network

Quick Start

git clone <repository-url>
cd SoundTouchMCP
cp appsettings.example.json appsettings.json
dotnet run

Devices are discovered automatically at runtime — use the DiscoverDevices or DiscoverDevicesOnSubnet tool from your MCP client.

Configuration

appsettings.json

Controls logging and discovery tuning. Copy appsettings.example.json to get started:

{
  "SoundTouch": {
    "Discovery": {
      "ProbeTimeoutMs": 3000,
      "Zeroconf": {
        "ScanTimeMs": 5000,
        "SocketRetries": 4,
        "SocketRetryDelayMs": 1000,
        "DiscoveryPasses": 2,
        "PassDelayMs": 700
      }
    }
  }
}

Setting	Purpose
Discovery:ProbeTimeoutMs	HTTP probe timeout for Zeroconf and subnet discovery
Discovery:Zeroconf:*	Tune Zeroconf resilience on unstable networks

Device store

Devices are persisted separately from appsettings.json:

OS	Path
macOS	~/Library/Application Support/SoundTouchMCP/devices.json
Windows	%APPDATA%/SoundTouchMCP/devices.json
Linux	$XDG_CONFIG_HOME/SoundTouchMCP/devices.json

Override with the SOUNDTOUCH_DEVICES_PATH environment variable.

If the store doesn't exist yet, it bootstraps from SoundTouch:Devices in appsettings.json (one-time).

Config file resolution

The server finds appsettings.json using the first match:

1. --config /path/to/appsettings.json (CLI argument)
2. SOUNDTOUCH_APPSETTINGS_PATH environment variable
3. SOUNDTOUCH_CONFIG_DIR environment variable → <dir>/appsettings.json
4. Next to the server executable
5. Server content root (fallback)

MCP Client Setup

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "soundtouch": {
      "command": "/absolute/path/to/SoundTouchMCP/publish/SoundTouchMCP",
      "args": [],
      "env": {
        "SOUNDTOUCH_CONFIG_DIR": "/absolute/path/to/your/config/folder"
      }
    }
  }
}

Or run via dotnet directly:

{
  "servers": {
    "soundtouch": {
      "command": "dotnet",
      "args": ["run", "--project", "/absolute/path/to/SoundTouchMCP/SoundTouchMCP.csproj"],
      "env": {
        "SOUNDTOUCH_CONFIG_DIR": "/absolute/path/to/your/config/folder"
      }
    }
  }
}

Then: Command Palette → MCP: List Servers → start soundtouch.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "soundtouch": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/SoundTouchMCP"],
      "env": {}
    }
  }
}

Publishing

# macOS (Apple Silicon)
dotnet publish ./SoundTouchMCP.csproj -c Release -r osx-arm64 --self-contained false -o ./publish

# Windows (x64)
dotnet publish ./SoundTouchMCP.csproj -c Release -r win-x64 --self-contained false -o ./publish-win

Other runtimes: osx-x64, linux-x64.

MCP Tools

Tool	Description	Key Parameters
DiscoverDevices	Discover devices via Zeroconf and update the store	removeNotFound, forceRefresh
DiscoverDevicesOnSubnet	Discover devices by scanning a subnet on port 8090	subnet (CIDR, e.g. 192.168.1.0/24; auto-detected if omitted), removeNotFound, forceRefresh
PowerControl	Turn a device on or off	deviceName, powerOn
VolumeUp	Increase volume by one step	deviceName
VolumeDown	Decrease volume by one step	deviceName
SetVolume	Set volume to a specific level (0–100)	deviceName, level
ListPresets	List all presets (1–6) for a device	deviceName
PlayPreset	Play a preset by name or number	deviceName, presetIdentifier
EnterBluetoothPairing	Enter Bluetooth pairing mode	deviceName
GetDeviceInfo	Get device type, ID, and IP	deviceName
ListDevices	List all configured devices	—

Tip: Use DiscoverDevices(forceRefresh: true) to fully reconcile the store with currently reachable devices (removes stale entries).

Subnet scan safety: prefix length must be between /16 and /30.

License

MIT

Contributing

Contributions welcome — feel free to open a Pull Request.