MusicBrainz MCP Server

Instructions

Implementation Reference

• mcp_musicbrainz/server.py:191-247 (handler)

  The handler function `browse_entities` that executes the tool logic for browsing MusicBrainz entities.

  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
      - recordings by artist: all recorded tracks
  
      Args:
          entity_type: What to list (releases, recordings, release-groups,
                       artists, labels, works, events, places)
          linked_type: The entity you're browsing by (artist, label,
                       recording, release, release_group, work, area, collection)
          linked_id: MBID of the linked entity
          limit: Results per page (max 100)
          offset: Paging offset
      """
      if entity_type not in BROWSE_FUNCS:
          return (
              f"Invalid entity type '{entity_type}'. "
              f"Choose from: {', '.join(BROWSE_FUNCS)}"
          )
      # Normalize hyphenated linked_type to underscore for musicbrainzngs kwargs
      normalized = linked_type.replace("-", "_")
      valid_for_entity = VALID_BROWSE_COMBINATIONS.get(entity_type, set())
      if normalized not in valid_for_entity:
          return (
              f"Invalid linked type '{linked_type}' for {entity_type}. "
              f"Valid linked types: {', '.join(sorted(valid_for_entity))}"
          )
  
      result = BROWSE_FUNCS[entity_type](
          **{normalized: linked_id, "limit": min(limit, 100), "offset": offset}
      )
      singular = entity_type.rstrip("s")
      list_key = f"{singular}-list"
      count_key = f"{singular}-count"
      items = result.get(list_key, [])
      count = result.get(count_key, len(items))
      lines = [f"Showing {len(items)} of {count} {entity_type} (offset {offset}):"]
      for i in items:
          name = i.get("title") or i.get("name", "?")
          date = i.get("first-release-date") or i.get("date", "")
          rtype = i.get("type") or i.get("primary-type", "")
          extra = " | ".join(filter(None, [date, rtype]))
          extra_str = f" ({extra})" if extra else ""
          lines.append(f"- {name}{extra_str} | {singular} ID: {i['id']}")
      return "\n".join(lines)