search_entities
Search the MusicBrainz database for artists, albums, recordings, labels, and other music entities using structured queries to find specific music metadata.
Instructions
Search for any MusicBrainz entity (artist, release, recording, label, work, release-group, area, event, instrument, place, series). Supports Lucene syntax. Example queries:
'artist:Nirvana AND country:US'
'release:Nevermind'
'recording:"Smells Like Teen Spirit"' PRIMARY DATA SOURCE. Search for artists, releases, or recordings. If an exact search (e.g., 'artist:Name') returns 0 results, try a broader search with just the name string. If still 0 results, use search_entities_fuzzy for typo-tolerant matching.
Entity hierarchy (IDs are NOT interchangeable):
artist: a person or group
release-group: an "album" concept (e.g. "Nevermind") — has type (Album, EP, Single)
release: a specific edition of a release-group (e.g. US CD vs JP vinyl)
a release contains one or more media (disc 1, disc 2, etc.)
each medium contains tracks (with position and optional title override)
recording: a unique audio track (a song). Tracks on a release point to recordings.
work: an abstract composition (lyrics + music), independent of any recording
label: a record label that publishes releases (not release-groups)
Every ID returned is an MBID (UUID) bound to a specific entity type. An MBID from a release-group CANNOT be used as a release_id, and vice versa. Always track which entity type an ID belongs to and pass it to the matching tool.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_type | Yes | ||
| query | Yes | ||
| limit | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- mcp_musicbrainz/server.py:144-205 (handler)The search_entities function acts as a dispatcher, validating the entity type and using the SEARCH_FUNCS map to call the appropriate musicbrainzngs search function, then formatting the results.
def search_entities(entity_type: str, query: str, limit: int = 5) -> str: """ Search for any MusicBrainz entity (artist, release, recording, label, work, release-group, area, event, instrument, place, series). Supports Lucene syntax. Example queries: - 'artist:Nirvana AND country:US' - 'release:Nevermind' - 'recording:"Smells Like Teen Spirit"' PRIMARY DATA SOURCE. Search for artists, releases, or recordings. If an exact search (e.g., 'artist:Name') returns 0 results, try a broader search with just the name string. If still 0 results, use search_entities_fuzzy for typo-tolerant matching. Entity hierarchy (IDs are NOT interchangeable): - artist: a person or group - release-group: an "album" concept (e.g. "Nevermind") — has type (Album, EP, Single) - release: a specific edition of a release-group (e.g. US CD vs JP vinyl) - a release contains one or more media (disc 1, disc 2, etc.) - each medium contains tracks (with position and optional title override) - recording: a unique audio track (a song). Tracks on a release point to recordings. - work: an abstract composition (lyrics + music), independent of any recording - label: a record label that publishes releases (not release-groups) Every ID returned is an MBID (UUID) bound to a specific entity type. An MBID from a release-group CANNOT be used as a release_id, and vice versa. Always track which entity type an ID belongs to and pass it to the matching tool. """ if entity_type not in SEARCH_FUNCS: return ( f"Invalid entity type '{entity_type}'. " f"Choose from: {', '.join(SEARCH_FUNCS)}" ) result = SEARCH_FUNCS[entity_type](query=query, limit=limit) list_key = f"{entity_type.replace('-', '_')}-list" items = result.get(list_key, []) lines = [f"Found {len(items)} results for {entity_type}:"] for i in items: name = i.get("name") or i.get("title") disambig = i.get("disambiguation", "") extra = f" ({disambig})" if disambig else "" lines.append(f"- {name}{extra} | {entity_type} ID: {i['id']}") return "\n".join(lines) @mcp.tool() @cached_tool() def browse_entities( entity_type: str, linked_type: str, linked_id: str, limit: int = 25, offset: int = 0, ) -> str: """ Browse MusicBrainz entities linked to another entity, with paging. Useful for getting complete discographies, all releases on a label, etc. Common combinations: - release-groups by artist: full discography - releases by release_group: all editions of an album - releases by label: label's catalog