listenbrainz-mcp

name	listenbrainz-mcp
description	Use ListenBrainz MCP server to interact with ListenBrainz REST API for listens, statistics, metadata, feedback, and popularity data. Provides 18 tools for querying user listening history, artist/track statistics, MusicBrainz-enriched metadata, user feedback (love/hate), and popularity rankings.

ListenBrainz MCP Server

When to use this skill

• When you need to query ListenBrainz user listening history, statistics, or metadata
• When you need to retrieve MusicBrainz-enriched track/artist/album information
• When you need to manage user feedback (love/hate) on recordings
• When you need to access popularity rankings for artists, recordings, or release groups
• When you need to fetch all listens for a time period with automatic pagination

When NOT to use this skill

• When you need to submit new listens to ListenBrainz (this MCP server is read-only)
• When you need to manage ListenBrainz user accounts or authentication
• When you need to interact with other music services (use their specific MCP servers instead)

Prerequisites

1. ListenBrainz account: You need a ListenBrainz account with an API token
2. Token location: Place your ListenBrainz API token at ~/.listenbrainz_token
3. Python 3.10+: Required for the MCP server
4. uv: Required for package management

Installation

1. Clone the repository and install:

   git clone https://github.com/serjflint/listenbrainz-mcp
   cd listenbrainz-mcp
   uv sync
   

2. Copy the skill to your agent skills directory:

   mkdir -p ~/.agents/skills/listenbrainz-mcp
   cp skill/SKILL.md ~/.agents/skills/listenbrainz-mcp/SKILL.md
   

3. Verify installation:

   listenbrainz-mcp --help
   

MCP Configuration

Add to your MCP settings JSON:

{
  "listenbrainz": {
    "type": "stdio",
    "command": "/path/to/.venv/bin/listenbrainz-mcp",
    "args": ["--transport", "stdio"]
  }
}

Available Tools

Listens (4 tools)

• get_listens - Retrieve user listening history with optional count and time range filters
• get_listens_for_period - Get all listens within a time period with automatic pagination (default: last 7 days); accepts days, min_ts, max_ts
• get_playing_now - Get the currently playing track for a user
• get_listen_count - Get total listen count for a user

Statistics (5 tools)

• get_top_artists - Get top artists by listen count; accepts range (week/month/year/all_time), count, offset
• get_top_recordings - Get top recordings by listen count
• get_top_releases - Get top releases/albums by listen count
• get_top_release_groups - Get top release groups by listen count
• get_listening_activity - Get listening activity over time; accepts range

Metadata (4 tools)

• get_recording_metadata - Get MusicBrainz-enriched metadata for recordings (by MBID)
• get_artist_metadata - Get MusicBrainz-enriched metadata for artists (by MBID)
• get_release_group_metadata - Get MusicBrainz-enriched metadata for release groups (by MBID)
• lookup_recording_by_name - Look up a recording by artist name and track name

Feedback (1 tool)

• get_feedback - Get user feedback (loved/hated tracks); accepts score (1=loved, -1=hated)

Popularity (4 tools)

• get_recording_popularity - Get popularity data for recordings (by MBID list)
• get_artist_popularity - Get popularity data for artists (by MBID list)
• get_top_recordings_for_artist - Get top recordings for an artist (by artist MBID)
• get_top_release_groups_for_artist - Get top release groups for an artist (by artist MBID)

Usage Examples

Get last week's scrobbles (all of them, paginated)

Use get_listens_for_period with days=7

Get recent listens (up to 100)

Use get_listens with count=100

Get currently playing track

Use get_playing_now

Get track metadata by MusicBrainz ID

Use get_recording_metadata with recording_mbids=["db042c82-882e-4fed-9a2f-f8de3becbc63"]

Get top artists this month

Use get_top_artists with range="this_month", count=25

Get loved tracks

Use get_feedback with score=1

Troubleshooting

Token not found

Ensure your ListenBrainz API token is at ~/.listenbrainz_token. Get your token from https://listenbrainz.org/settings/

API errors

The MCP server uses exponential backoff retry logic for transient failures. Check your network connection and ListenBrainz API status.

Empty results

Some tools may return empty results if:

• The user has no listening history in the requested period
• The MBID is invalid or not found in MusicBrainz
• The time range filter excludes all data

Related Resources

• ListenBrainz API documentation: https://listenbrainz.readthedocs.io/en/latest/api/api.html
• ListenBrainz website: https://listenbrainz.org
• MusicBrainz: https://musicbrainz.org