Music MCP
A Model Context Protocol (MCP) server for controlling Apple Music on macOS using AppleScript. This connector provides a structured interface for AI assistants like Claude to interact with the Music app, enabling playback control, library management, and music information retrieval.
Features
- Playback Control: Play, pause, skip tracks, and control volume
- Current Track Information: Get detailed track metadata and playback status
- Library Management: Search tracks, albums, artists, and browse your library
- Playlist Management: Create, manage, modify, and play playlists
- Enhanced Queue Management: Add tracks to play next, view queue status, and control playback order
- Smart "Play Next" Feature: Queue tracks to play after the current song using temporary playlists
- Diagnostic Tools: Built-in info command for troubleshooting
Requirements
- macOS (required for Apple Music and AppleScript)
- Node.js 18.0.0 or higher
- Apple Music app installed and accessible
- Automation permissions granted to your terminal/app
Installation
Via npm (Recommended)
npx @pedrocid/music-mcp@latest
For Development
git clone https://github.com/pedrocid/music-mcp.git
cd music-mcp
npm install
npm run build
Building as Desktop Extension
If you want to create a Desktop Extension (.dxt) for distribution:
# Install the DXT CLI tool
npm install -g @anthropic-ai/dxt
# Initialize Desktop Extension (if not already done)
dxt init
# Build the project
npm run build
# Package the extension
dxt pack
This creates a music-mcp.dxt file that can be installed directly in Claude Desktop or submitted to the Anthropic extension directory.
Note: The .dxt file is not included in the repository as it's a build artifact. Users who want the Desktop Extension should build it themselves using the instructions above.
Configuration
Claude Desktop Configuration
Add this to your Claude Desktop MCP configuration:
{
"mcpServers": {
"music": {
"command": "npx",
"args": ["@pedrocid/music-mcp@latest"]
}
}
}
Environment Variables (Optional)
All environment variables are optional. The server uses stderr logging by default and works without any configuration.
| Variable | Default | Description |
|---|---|---|
MUSIC_MCP_LOG_LEVEL | info | Log level (debug, info, warn, error) |
MUSIC_MCP_FILE_LOGGING | false | Enable file logging (disabled by default) |
MUSIC_MCP_LOG_FILE | ~/Library/Logs/music-mcp.log | Log file location (only used if file logging enabled) |
MUSIC_MCP_CACHE_TTL | 300 | Cache timeout in seconds |
MUSIC_MCP_MAX_SEARCH_RESULTS | 50 | Maximum search results |
MUSIC_MCP_TIMEOUT_SECONDS | 30 | Default timeout for operations |
MUSIC_MCP_ARTWORK_EXPORT | true | Enable album artwork export |
MUSIC_MCP_LENIENT_PARSING | true | Accept variations in parameter names |
Available Tools
info
Get diagnostic information about the MCP server status.
{
"command": "info"
}
Returns version information, Music app availability, and configuration status.
execute_music_command
Execute music playback control commands.
{
"command": "play|pause|next|previous|toggle_playback",
"volume": 75,
"position": 30,
"shuffleMode": true,
"repeatMode": "all",
"rating": 4
}
get_music_info
Retrieve information about current playback or library.
{
"infoType": "current_track|playback_status|queue|library_stats",
"format": "simple|detailed"
}
search_music
Search the music library.
{
"query": "artist name or song title",
"searchType": "all|track|album|artist|playlist",
"limit": 25
}
manage_playlist
Create and manage playlists.
{
"action": "create|add_track|remove_track|rename|delete|list|get_tracks",
"playlistName": "My Playlist",
"trackId": "search term for track",
"newName": "New Playlist Name"
}
queue_music ✨ NEW
Enhanced queue management and playlist control.
{
"action": "view_queue|add_to_queue|play_queue|clear_queue|play_playlist",
"trackSearchTerm": "song or artist name",
"playlistName": "My Playlist",
"shuffle": true
}
Queue Actions:
view_queue: See current track, playlist context, and playback statusadd_to_queue: Add tracks to a temporary "Up Next" queue for sequential playbackplay_queue: Play the tracks you've added to the queueclear_queue: Clear all tracks from the up next queueplay_playlist: Play a specific playlist (with optional shuffle)
Permissions
When first using the MCP server, macOS will prompt you to grant automation permissions. You need to:
- Allow your terminal app (Terminal.app, iTerm2, etc.) to control "Music"
- Go to System Preferences > Security & Privacy > Privacy > Automation
- Ensure your terminal app has permission to control "Music"
Troubleshooting
Check Server Status
npx @pedrocid/music-mcp@latest
# Then use the info tool to check status
Common Issues
"Music app is not running"
- The server automatically launches the Music app when needed
- If issues persist, manually open the Music app first
"AppleScript execution failed"
- Grant automation permissions in System Preferences
- Ensure Music app is accessible and not restricted
"No tracks found"
- Check that you have music in your library
- Verify your Apple Music subscription is active
Debugging
The server logs to stderr by default, which Claude Desktop captures. For additional debugging, you can:
- Check Claude Desktop's MCP logs
- Enable file logging by setting
MUSIC_MCP_FILE_LOGGING=trueenvironment variable - Use the
infotool to check server diagnostics
Example Usage
Here are some example interactions you can have with Claude using this MCP server:
Basic Playback:
- "Play my music and set the volume to 50%"
- "What song is currently playing?"
- "Skip to the next track"
Library & Search:
- "Search for songs by Taylor Swift"
- "Show me my library statistics"
Playlist Management:
- "Create a playlist called 'Road Trip' and add some upbeat songs"
- "Play my 'Chill' playlist with shuffle enabled"
- "Remove all tracks by [artist] from my 'Favorites' playlist"
Queue Management (NEW):
- "Add 'Bohemian Rhapsody' to play next"
- "Show me what's in my up next queue"
- "Clear my queue and add these 3 songs to play after the current track"
- "Play my 'Party Mix' playlist next"
Development
Building
npm run build
Testing
npm test # Unit tests
npm run test:e2e # Integration tests
Linting
npm run lint
Release Preparation
npm run prepare-release
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make your changes and add tests
- Run the test suite:
npm test - Run the release preparation:
npm run prepare-release - Commit your changes:
git commit -am 'Add feature' - Push to the branch:
git push origin feature-name - Submit a pull request
License
MIT License - see the LICENSE file for details.