MusicBrainz MCP Server

Instructions

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