apple-music-local-plugin

**English** | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-HK.md) [![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url] [![Upstream Release][release-shield]][release-url] [![Python][python-shield]][python-url] <br /> <div align="center"> <a href="https://github.com/mikotokuroko/apple-music-local-plugin"> <img src="images/logo.svg" alt="Apple Music Local logo" width="96" height="96"> </a> <h3 align="center">Apple Music Local for Codex</h3> <p align="center"> Control your own Apple Music library, playlists, playback, and queue from a local Windows or macOS Codex session. <br /> <strong>No public tunnel. No OpenAI API key. No prepaid API credits.</strong> <br /><br /> <a href="#getting-started"><strong>Get started »</strong></a> <br /><br /> <a href="https://github.com/mikotokuroko/apple-music-local-plugin/issues/new?labels=bug">Report Bug</a> &middot; <a href="https://github.com/mikotokuroko/apple-music-local-plugin/issues/new?labels=enhancement">Request Feature</a> </p> </div> ## Disclaimer > **MIT · Unofficial community project — not affiliated with or endorsed by Apple. Uses your own Apple Music account for personal use; follow Apple's terms.** <details> <summary>Table of Contents</summary> <ol> <li><a href="#about-the-project">About The Project</a></li> <li><a href="#features">Features</a></li> <li><a href="#tech-stack">Tech Stack</a></li> <li><a href="#getting-started">Getting Started</a></li> <li><a href="#usage">Usage</a></li> <li><a href="#troubleshooting">Troubleshooting</a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> <li><a href="#contact">Contact</a></li> <li><a href="#acknowledgments">Acknowledgments</a></li> </ol> </details> ## About the Project This is a local plugin consisting of a **Codex Plugin + Skill**. Because Codex's built-in Apple Music plugin cannot access a personal Apple Music library, this project packages [`applemusic-mcp`](https://github.com/epheterson/applemusic-mcp) as an installable and shareable local Codex plugin. Codex uses only the Apple Music authentication on your own computer; data is processed locally and never uploaded to the cloud. No API credits or self-hosted MCP service are required. | Component | What it does | |---|---| | **Plugin — Apple Music Local** | Connects Codex to the local `applemusic-mcp` service. It provides the actual tools for reading your library and playlists, searching Apple Music, finding related music, changing playlists, controlling playback, and managing the queue. | | **Skill — apple-music** | Tells Codex when and how to use those tools. It interprets prompts, chooses the correct workflow, applies safety rules, and controls the final response format. | ## Features - Browse and search your library, playlists, recently played, and recently added music. - Search the Apple Music catalog, charts, recommendations, artists, albums, and songs. - Create, rename, organize, populate, and delete playlists. - Add or remove library items and use supported love, dislike, or rating actions. - Play, pause, skip, seek, and control shuffle, repeat, and volume. - View and edit the Up Next queue through Safari on macOS or local Chrome on Windows. - Export supported results as text, JSON, or CSV. ## Tech Stack - [Python 3.10+](https://www.python.org/) - [Model Context Protocol](https://modelcontextprotocol.io/) - [applemusic-mcp](https://github.com/epheterson/applemusic-mcp) - [Codex plugin format](https://developers.openai.com/plugins/build/plugins) - Local STDIO transport The bundled [`applemusic-mcp`](https://github.com/epheterson/applemusic-mcp) routes each request to the right local engine: **Music.app** through AppleScript for native macOS library, playlist, and playback operations; **Safari MusicKit** for the macOS web player and Up Next queue; and the Apple Music API or Chrome where appropriate. See the [upstream capability table](https://github.com/epheterson/applemusic-mcp#features) for the full set of limitations. ## Getting Started ### Prerequisites - Windows 10 or Windows 11, or macOS 15 or later - Python 3.10 or newer - [`pipx`](https://pipx.pypa.io/stable/installation/) - Google Chrome on Windows; Safari is used by default on macOS - Codex or the ChatGPT desktop app with local plugin support ### Installation 1. Open a terminal and install the MCP service. ```bash pipx install applemusic-mcp ``` 2. Sign in to Apple Music once, then verify the status. ```bash applemusic-mcp login applemusic-mcp status ``` On **macOS**, sign in at [music.apple.com](https://music.apple.com) in Safari first. Then enable **Safari → Settings → Advanced → Show features for web developers**, and in the **Develop** menu enable **Allow JavaScript from Apple Events**. This lets `applemusic-mcp` read the Apple Music session token from your own signed-in Safari. You can disable the setting after sign-in. Music.app and Safari are then used automatically; Chrome and Playwright are not required for the default macOS setup. On **Windows**, `login` opens a local Chrome window for Apple Music sign-in. 3. Add the plugin marketplace. ```powershell codex plugin marketplace add mikotokuroko/apple-music-local-plugin ``` 4. Restart the ChatGPT desktop app, open the Plugins Directory, select **Apple Music Local**, and install it. 5. Start a new Codex chat and enter: `List my Apple Music playlists.` ## Usage Just talk to Apple Music Local: - `@Apple Music Local suggest 5 songs based on my "hello" playlist.` - `Suggest peaceful songs.` — returns 5 songs when no count is given. - `Create a playlist called "Road Trip" with upbeat 90s alternative.` — creates it with 25 tracks when no count is given. - `Add "Hey Jude" to my "Road Trip" playlist.` - `Drop the last 3 tracks from my workout playlist.` - `Organize my playlists into Rock, Jazz, and Electronic folders.` - `Play my workout playlist on shuffle, then play "Bohemian Rhapsody" next.` - `What have I been listening to lately, and what is topping the charts?` - `Analyze my "Japanese" playlist and generate a reusable taste profile for a scheduled task.` - `Export my library to CSV.` Apple Music Local asks a short clarification when a song, playlist, action, or destination is genuinely ambiguous. It previews destructive changes before performing them and skips duplicate playlist additions by default. ### Example response Prompt: `@Apple Music Local suggest 5 songs based on my "Japanese" playlist.` Example response: > I found your 46-track **Japanese** playlist: it leans toward King Gnu, > YOASOBI, Aimer, RADWIMPS, and anime-adjacent emotional J-pop/rock. These five > are verified picks not already in it: > > 1. [Setting Sun (斜陽) — Yorushika](https://music.apple.com/mo/album/setting-sun/1684164647?i=1684164654&l=en-GB) — reflective, cinematic alternative pop. > 2. [Idol (アイドル) — YOASOBI](https://music.apple.com/mo/album/%E3%82%A2%E3%82%A4%E3%83%89%E3%83%AB/1707581102?i=1707581765&l=en-GB) — a sharper, high-energy YOASOBI lane. > 3. [Kaiju no Hanauta (怪獣の花唄) — VAUNDY](https://music.apple.com/mo/album/%E6%80%AA%E7%8D%A3%E3%81%AE%E8%8A%B1%E5%94%84-replica/1714599649?i=1714599800&l=en-GB) — big sing-along rock energy. > 4. [Subtitle — OFFICIAL HIGE DANDISM](https://music.apple.com/mo/album/subtitle/1648108987?i=1648108988&l=en-GB) — emotional, piano-led J-pop. > 5. [Kizuna No Kiseki (絆ノ奇跡) — MAN WITH A MISSION & milet](https://music.apple.com/mo/album/%E7%B5%86%E3%83%8E%E5%A5%87%E8%B7%A1/1678949877?i=1678949889&l=en-GB) — adds a punchier anime-rock duet. Prompt: `Suggest 5 songs for a good morning playlist.` Example response: > For a bright Japanese-pop **Good Morning** playlist: > > 1. [Good Morning — Awesome City Club](https://music.apple.com/mo/album/good-morning/1617637470?i=1617637471&l=en-GB) > 2. [Koi — Gen Hoshino](https://music.apple.com/mo/album/koi/1156375337?i=1156375396&l=en-GB) > 3. [Niji — Masaki Suda](https://music.apple.com/mo/album/niji/1537793753?i=1537793754&l=en-GB) > 4. [Walking with You — Novelbright](https://music.apple.com/mo/album/walking-with-you/1444839833?i=1444839834&l=en-GB) > 5. [Soranji — Mrs. GREEN APPLE](https://music.apple.com/mo/album/soranji/1823814178?i=1823814186&l=en-GB) > > This starts gentle, turns sunny, then ends with a bit of lift. Codex may show Apple Music tool progress separately. The same matched songs may render as linked tracks on desktop or as a native Apple Music card on iPhone. ### Playlist recommendation cards When you ask for a fixed number of songs based on a named playlist, Apple Music Local reads that playlist and uses official Apple Music catalog suggestions. The selected songs are then matched and rendered by the official Apple Music app. Depending on the client, the same official result may appear as a linked song response like the examples above or as an Apple Music collection card. The source playlist is not modified automatically. The official Apple Music app must be connected. If it is unavailable, the plugin stops and asks you to connect it rather than returning an unverified text-only recommendation list. If you omit the number of songs, the default is 5. If you write only `Suggest songs`, the plugin asks for a genre, mood, activity, artist, other song type, or a playlist name. Once that preference is known, it returns the Apple Music result without asking for a number. | Tool | Main capabilities | |---|---| | `playlist` | Browse, search, create, rename, organize, add, remove, copy, or delete playlists | | `library` | Browse and search the library, recent activity, favorites, add or remove items, ratings, and snapshots | | `catalog` | Search and resolve songs, albums, artists, genres, and suggestions | | `discover` | Recommendations, charts, heavy rotation, stations, and similar artists | | `playback` | Play, pause, skip, seek, now playing, shuffle, repeat, and volume | | `queue` | View or edit Up Next, including play next, play later, remove, jump, and clear | | `config` | Status, sign-in/out, preferences, storefronts, and audit information | ### Phone access Use [ChatGPT Remote](https://learn.chatgpt.com/docs/remote-connections) to control Apple Music Local from your phone: 1. On the computer, open **Settings → Connections → Control this PC → Set up**. 2. Scan the QR code with the ChatGPT mobile app and finish verification. 3. On your phone, open **Remote**, select the computer, and start or continue your Apple Music Local task. Keep the computer awake, online, signed in to the same ChatGPT account, and running the desktop app. The plugin and playback remain on the computer. ## Troubleshooting ### `/mcp` shows `auth unsupported` This is expected. The local STDIO service authenticates through `applemusic-mcp login`, not MCP OAuth. Run `applemusic-mcp status`; a working setup includes `User token: present` and `API: ok`. ### Cannot find the `applemusic-mcp` command Run `pipx ensurepath`, close and reopen PowerShell, then try again. ## Contributing 1. Fork this repository. 2. Create a feature branch: `git checkout -b feature/AmazingFeature`. 3. Commit your changes: `git commit -m "Add AmazingFeature"`. 4. Push the branch: `git push origin feature/AmazingFeature`. 5. Open a Pull Request. Do not include Apple Music sign-in information, tokens, cookies, `.p8` files, or local authentication data in an Issue or Pull Request. ## License MIT · Unofficial community project — not affiliated with or endorsed by Apple. Uses your own Apple Music account for personal use; follow Apple's terms. See [`LICENSE`](LICENSE) for details. ## Contact Email: hoicheoklam@gmail.com Project: [github.com/mikotokuroko/apple-music-local-plugin](https://github.com/mikotokuroko/apple-music-local-plugin) ## Acknowledgments - [alwinecor](https://github.com/alwinecor) for the original idea - [applemusic-mcp](https://github.com/epheterson/applemusic-mcp) - [Best README Template](https://github.com/othneildrew/Best-README-Template) - [Shields.io](https://shields.io/) - [contrib.rocks](https://contrib.rocks/) [contributors-shield]: https://img.shields.io/github/contributors/mikotokuroko/apple-music-local-plugin.svg?style=for-the-badge [contributors-url]: https://github.com/mikotokuroko/apple-music-local-plugin/graphs/contributors [forks-shield]: https://img.shields.io/github/forks/mikotokuroko/apple-music-local-plugin.svg?style=for-the-badge [forks-url]: https://github.com/mikotokuroko/apple-music-local-plugin/network/members [stars-shield]: https://img.shields.io/github/stars/mikotokuroko/apple-music-local-plugin.svg?style=for-the-badge [stars-url]: https://github.com/mikotokuroko/apple-music-local-plugin/stargazers [issues-shield]: https://img.shields.io/github/issues/mikotokuroko/apple-music-local-plugin.svg?style=for-the-badge [issues-url]: https://github.com/mikotokuroko/apple-music-local-plugin/issues [license-shield]: https://img.shields.io/github/license/mikotokuroko/apple-music-local-plugin.svg?style=for-the-badge [license-url]: https://github.com/mikotokuroko/apple-music-local-plugin/blob/main/LICENSE [release-shield]: https://img.shields.io/github/v/release/epheterson/applemusic-mcp.svg?style=for-the-badge&label=upstream [release-url]: https://github.com/epheterson/applemusic-mcp/releases [python-shield]: https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?style=for-the-badge&logo=python&logoColor=white [python-url]: https://www.python.org/downloads/ [downloads-shield]: https://static.pepy.tech/badge/applemusic-mcp [downloads-url]: https://pepy.tech/project/applemusic-mcp [mcp-shield]: https://img.shields.io/badge/MCP-server-6f42c1.svg?style=for-the-badge [mcp-url]: https://modelcontextprotocol.io/ Built with broke bank account in Melbourne by @mikotokuroko and Codex.