{
  "markdown": "# mcp-apple-music 🎵\n\nmcp-name: io.github.Cifero74/mcp-apple-music\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)\n\nAn **MCP (Model Context Protocol) server** that gives Claude full access to your Apple Music account — search the catalog, browse your personal library, manage playlists, and explore your listening history and recommendations.\n\n> **Ask Claude things like:**\n> - *\"Based on what I've been listening to lately, recommend 15 songs I don't have yet and add them to a new playlist\"*\n> - *\"Show me all my playlists and tell me which artists appear most\"*\n> - *\"Search for albums by Nick Cave and add my three favourites to a playlist called Dark Picks\"*\n\n---\n\n## Features\n\n| Tool | Description |\n|---|---|\n| `search_catalog` | Search Apple Music catalog (songs, albums, artists, playlists) |\n| `search_library` | Search within your personal library |\n| `get_library_songs` | List songs saved in your library (paginated) |\n| `get_library_albums` | List albums in your library (paginated) |\n| `get_library_artists` | List artists in your library |\n| `get_library_playlists` | List all your playlists with IDs |\n| `get_playlist_tracks` | Get tracks inside a specific playlist |\n| `create_playlist` | Create a new playlist |\n| `add_tracks_to_playlist` | Add songs to a playlist (library or catalog tracks) |\n| `get_recently_played` | See recently played albums/playlists/stations |\n| `get_recommendations` | Get personalised Apple Music picks |\n\n---\n\n## Requirements\n\n- Python 3.10+\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n- An **Apple Developer account** (free tier is fine) with a MusicKit key\n- An active **Apple Music subscription**\n\n---\n\n## Setup\n\n### 1. Create a MusicKit Key\n\n1. Go to [developer.apple.com](https://developer.apple.com) → **Certificates, Identifiers & Profiles**\n2. Under **Keys**, click **+** to create a new key\n3. Give it any name, enable **MusicKit**, and click **Continue → Register**\n4. **Download** the `.p8` file — you can only download it once, keep it safe!\n5. Note your **Key ID** (e.g. `ABC123DEF4`) and your **Team ID** (found under *Membership Details*)\n\n> ⚠️ The Key ID is the alphanumeric code shown next to the key name — **not** the filename of the `.p8` file.\n\n### 2. Clone and install\n\n```bash\ngit clone https://github.com/marioinghilleri/mcp-apple-music\ncd mcp-apple-music\n\n# with uv (recommended)\nuv sync\n\n# or with pip\npip install -e .\n```\n\n### 3. Run the one-time setup wizard\n\n```bash\n# with uv\nuv run mcp-apple-music-setup\n\n# or directly\npython -m mcp_apple_music.setup\n```\n\nThe wizard will ask for your **Team ID**, **Key ID**, and the path to your `.p8` file. It then opens a browser page where you click **\"Authorise Apple Music\"** — this uses Apple's official MusicKit JS to obtain your Music User Token, which is stored securely at `~/.config/mcp-apple-music/config.json` (file permissions: `600`).\n\n### 4. Add to Claude Desktop\n\nOpen your Claude Desktop config:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"apple-music\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/absolute/path/to/mcp-apple-music\",\n        \"mcp-apple-music\"\n      ]\n    }\n  }\n}\n```\n\nRestart Claude Desktop — you should see the apple-music tools available in the toolbar.\n\n---\n\n## How it works\n\nApple Music requires two separate tokens:\n\n- **Developer Token** — a JWT you sign locally with your `.p8` private key. Valid up to 6 months; the server regenerates it automatically before expiry. Your key never leaves your machine.\n- **Music User Token** — obtained once via MusicKit JS OAuth in the browser (the setup wizard handles this). Stored locally at `~/.config/mcp-apple-music/config.json`.\n\n```\nYour .p8 key  ──►  Developer Token (JWT, auto-renewed)  ─┐\n                                                           ├──► Apple Music API\nBrowser OAuth ──►  Music User Token (stored locally)    ─┘\n```\n\n> ⚠️ **Playback control** (play/pause/skip) is not available via Apple's REST API. It requires native MusicKit frameworks (iOS/macOS app) or MusicKit JS running in a browser context.\n>\n> For playback control, check out [chrome-relay](https://chrome-relay.kushalsm.com) — a companion CLI that lets an MCP server drive a `music.apple.com` tab already open in Chrome, enabling play/pause/skip without shipping a MusicKit JS shim.\n\n---\n\n## Project structure\n\n```\nmcp-apple-music/\n├── src/\n│   └── mcp_apple_music/\n│       ├── __init__.py\n│       ├── auth.py      — Developer Token generation + User Token management\n│       ├── client.py    — Async HTTP client for api.music.apple.com\n│       ├── server.py    — FastMCP server with all 11 tools\n│       └── setup.py     — One-time setup wizard (browser-based OAuth)\n├── config.example.json  — Example config structure (no secrets)\n├── pyproject.toml\n└── README.md\n```\n\n---\n\n## Example prompts\n\nOnce connected, you can ask Claude:\n\n```\n\"What have I been listening to this week? Based on that, find 10 songs\n I don't own yet that I'd probably enjoy and create a playlist with them.\"\n\n\"Search for all albums by Joni Mitchell and tell me which ones\n I already have in my library.\"\n\n\"List my playlists, pick the one that looks most like a workout mix,\n and add 5 high-energy songs from the catalog to it.\"\n\n\"Create a playlist called 'Rainy Sunday' with the 10 most mellow tracks\n you can find from my library.\"\n```\n\n---\n\n## Authors\n\nBuilt by **[Cifero74](https://github.com/Cifero74)** and **[Claude](https://claude.ai)** (Anthropic) as part of a personal MCP ecosystem for Claude Desktop.\n\nThis project was conceived, designed, debugged, and shipped entirely through a collaborative conversation between Mario and Claude — from API research and auth flow design, through the setup wizard, to live testing with a real Apple Music library.\n\nContributions, issues and PRs are welcome!\n\n---\n\n## License\n\n[MIT](LICENSE) — use it, fork it, build on it.\n",
  "bytes": 6183,
  "sha": "f12eda589b57cf281dea2ec024a5d03e6d3919b38274198cce613e85705fa99e",
  "repo_slug": "cifero74/mcp-apple-music",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cifero74_mcp_apple_music_8d4d32e7/readme"
}