apple-music-dj

Apple Music DJ & Playback Controller

A production-grade agent skill to control Apple Music natively on macOS and deliver professional, beat-matched DJ sets using the mcp-applemusic FastMCP server.

---

1. Prerequisites & Environment Setup

This skill communicates with macOS Music.app via AppleScript through the mcp-applemusic server.

Agent MCP Configuration

To equip your agent with the tools, ensure apple-music-mcp is configured in your agent's MCP settings:

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "applemusic": {
      "command": "uvx",
      "args": ["apple-music-mcp"]
    }
  }
}

For Cursor / Windsurf / VS Code (.cursor/mcp.json or Cline settings):

{
  "mcpServers": {
    "applemusic": {
      "command": "uvx",
      "args": ["apple-music-mcp"]
    }
  }
}

macOS Permission Note: On first execution, macOS will prompt to grant the host application permission to control "Music". Users must click Allow (or toggle it on under System Settings → Privacy & Security → Automation).

---

2. Tool Reference & Execution Workflows

Playback & Audio Controls

• Play / Resume: Call itunes_play or itunes_play_song(song_name, artist_name).
• Pause / Stop: Call itunes_pause.
• Skip / Previous: Call itunes_next or itunes_previous.
• Volume Control: Call itunes_set_volume(volume) (0–100 scale).
• Multi-Room & AirPlay Devices: Call itunes_list_devices to inspect connected devices, and itunes_set_device(device_name) or itunes_set_device_volume(device_name, volume) to adjust remote AirPlay endpoints.
• Equalizer & Modes: Call itunes_set_eq(preset) (e.g. "Hip-Hop", "Electronic", "Acoustic"), itunes_set_shuffle_mode(mode), and itunes_repeat(mode).

Search & Music Discovery

• Local Library Search: Call itunes_search(query) for locally added/downloaded music.
• Apple Music Catalog Search: Call itunes_search_catalog(query, entity) to search the entire worldwide Apple Music streaming catalog.
• Charts & New Releases: Call itunes_get_top_charts(genre) or itunes_get_new_releases().
• Universal Share Links: Call itunes_generate_share_link(song_name, artist) to create a universal song.link / Odesli link spanning Spotify, YouTube Music, and Tidal.
• Spotify Importer: Call itunes_import_from_spotify(spotify_url) to parse public Spotify playlists/albums and import matching tracks into Apple Music without API keys.
• Synchronized Lyrics: Call itunes_get_lyrics(song_name, artist_name) to pull synced lyrics from LRCLIB.