search_catalog
Search the Apple Music catalog to find songs, albums, artists, or playlists using specific search terms and filters.
Instructions
Search the Apple Music catalog for songs, albums, artists, or playlists.
Args: query: Search term (e.g. "Radiohead", "Bohemian Rhapsody"). types: Comma-separated resource types to include. Options: songs, albums, artists, playlists (default: songs,albums,artists) limit: Results per type, 1ā25 (default 5).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| types | No | songs,albums,artists | |
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/mcp_apple_music/server.py:94-150 (handler)Implementation of the 'search_catalog' tool. It interacts with the Apple Music catalog API based on the provided query and filters.
@mcp.tool() async def search_catalog( query: str, types: str = "songs,albums,artists", limit: int = 5, ) -> str: """Search the Apple Music catalog for songs, albums, artists, or playlists. Args: query: Search term (e.g. "Radiohead", "Bohemian Rhapsody"). types: Comma-separated resource types to include. Options: songs, albums, artists, playlists (default: songs,albums,artists) limit: Results per type, 1ā25 (default 5). """ client = _get_client() storefront = client.auth.get_storefront() data = await client.get( f"/catalog/{storefront}/search", params={"term": query, "types": types, "limit": min(max(1, limit), 25)}, user_auth=False, ) results = data.get("results", {}) lines = [f"š Catalog search: '{query}'\n"] if songs := results.get("songs", {}).get("data", []): lines.append("šµ Songs:") for i, s in enumerate(songs, 1): lines.append(_fmt_song(s, i)) if albums := results.get("albums", {}).get("data", []): lines.append("\nšæ Albums:") for i, a in enumerate(albums, 1): lines.append(_fmt_album(a, i)) if artists := results.get("artists", {}).get("data", []): lines.append("\nš¤ Artists:") for i, a in enumerate(artists, 1): lines.append(_fmt_artist(a, i)) if playlists := results.get("playlists", {}).get("data", []): lines.append("\nš Playlists:") for i, p in enumerate(playlists, 1): a = p.get("attributes", {}) lines.append( f" {i}. {a.get('name', '?')} ā {a.get('curatorName', '')} | ID: {p.get('id', '?')}" ) if len(lines) == 1: return f"No results found for '{query}'." return "\n".join(lines) # ------------------------------------------------------------------ # # Tool: search_library # # ------------------------------------------------------------------ #