search_library
Find songs, albums, artists, and playlists in your personal Apple Music library using search queries and customizable filters.
Instructions
Search within your personal Apple Music library.
Args: query: Search term. types: Comma-separated types. Options: library-songs, library-albums, library-artists, library-playlists limit: Results per type, 1ā25 (default 10).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| types | No | library-songs,library-albums,library-artists,library-playlists | |
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/mcp_apple_music/server.py:151-195 (handler)The implementation of the search_library tool, decorated with @mcp.tool() and utilizing the Apple Music API's library search endpoint.
@mcp.tool() async def search_library( query: str, types: str = "library-songs,library-albums,library-artists,library-playlists", limit: int = 10, ) -> str: """Search within your personal Apple Music library. Args: query: Search term. types: Comma-separated types. Options: library-songs, library-albums, library-artists, library-playlists limit: Results per type, 1ā25 (default 10). """ client = _get_client() data = await client.get( "/me/library/search", params={"term": query, "types": types, "limit": min(max(1, limit), 25)}, ) results = data.get("results", {}) lines = [f"š Library search: '{query}'\n"] if songs := results.get("library-songs", {}).get("data", []): lines.append("šµ Songs:") for i, s in enumerate(songs, 1): lines.append(_fmt_song(s, i)) if albums := results.get("library-albums", {}).get("data", []): lines.append("\nšæ Albums:") for i, a in enumerate(albums, 1): lines.append(_fmt_album(a, i)) if artists := results.get("library-artists", {}).get("data", []): lines.append("\nš¤ Artists:") for i, a in enumerate(artists, 1): lines.append(_fmt_artist(a, i)) if playlists := results.get("library-playlists", {}).get("data", []): lines.append("\nš Playlists:") for i, p in enumerate(playlists, 1): lines.append(_fmt_playlist(p, i)) if len(lines) == 1: return f"Nothing found in your library for '{query}'." return "\n".join(lines)