This file provides guidance to Claude Code when working with the SoundCloud MCP Server.
Sign in to like and favorite skills
This file provides guidance to Claude Code when working with the SoundCloud MCP Server.
MCP server for downloading tracks from SoundCloud and playing them on Chromecast/speakers via Home Assistant. Self-contained service that runs on nas01.
SoundCloud → scdl (download) → Local Storage → Flask (serve) → Home Assistant → Chromecast
Language: Python 3.11 Framework: Flask Transport: HTTP (MCP protocol) on port 3040 Deployment: nas01 via Docker
| Tool | Description |
|---|---|
| Download tracks from a SoundCloud URL |
| List all downloaded artists |
| List tracks for an artist |
| Search tracks by name |
| Play a track on a speaker via Home Assistant |
| Play any audio URL on a speaker |
| List available media players from Home Assistant |
| List all SoundCloud subscriptions being tracked |
| Add a SoundCloud artist/playlist to track |
| Remove a subscription |
| Download new tracks from all subscriptions |
| Get most recent downloads per artist, sorted by date |
GET /healthGET /audio/{artist}/{filename}GET /mcp/list_toolsPOST /mcp/call_toolPOST /mcp| Variable | Description | Default |
|---|---|---|
| Server port | 3040 |
| Directory for config (podcasts.json, archives) | /data |
| Directory for audio files (clean for Plex) | /music |
| Public URL for serving audio (use IP for Chromecast) | http://192.168.11.14:3040 |
| Home Assistant URL | https://nas01.local.jbmurphy.com:8123 |
| Home Assistant long-lived access token | (required) |
Note:
BASE_URL.jbmurphy.com| Container Path | Host Path | Purpose |
|---|---|---|
| | Config files (podcasts.json, archive files) |
| | Audio files only (clean for Plex/media servers) |
cd mcp-soundcloud # Use the build script ./build.sh # Or manually: docker buildx build --platform linux/amd64 -t registry.local.jbmurphy.com/mcp-soundcloud:latest --push .
# SSH to nas01 or use Portainer docker pull registry.local.jbmurphy.com/mcp-soundcloud:latest # Create .env file with required variables cat > .env << 'EOF' HA_TOKEN=your_home_assistant_token BASE_URL=http://192.168.11.14:3040 EOF # Create directories mkdir -p /volume1/docker/mcp-soundcloud/data mkdir -p /volume1/Music/soundcloud # Start the container docker-compose up -d
mcp-soundcloud.local.jbmurphy.comnas01.local.jbmurphy.com:3040redis-cli -h redis.local.jbmurphy.com -p 32383 SET mcp:soundcloud https://mcp-soundcloud.local.jbmurphy.com
from mcp import discover discover.call_tool('soundcloud_download', url='https://soundcloud.com/aboveandbeyond/tracks')
discover.call_tool('soundcloud_list_artists')
discover.call_tool('soundcloud_play', artist='aboveandbeyond', track='group therapy', player='media_player.family_room_speaker' )
discover.call_tool('soundcloud_list_players')
# Add a subscription discover.call_tool('soundcloud_add_subscription', url='https://soundcloud.com/aboveandbeyond/tracks') # List all subscriptions discover.call_tool('soundcloud_list_subscriptions') # Sync all subscriptions (download new tracks) discover.call_tool('soundcloud_sync') # Sync with limit (download only last N tracks per artist) discover.call_tool('soundcloud_sync', limit=5) # Remove a subscription discover.call_tool('soundcloud_remove_subscription', name='aboveandbeyond')
# Get most recent download for each artist (sorted by newest) discover.call_tool('soundcloud_get_recent_downloads') # Get last 3 downloads per artist discover.call_tool('soundcloud_get_recent_downloads', limit=3)
To migrate data from the old jbapi-rss setup:
# Copy existing podcasts to the new data volume docker cp /path/to/old/podcasts/. mcp-soundcloud:/data/