listenbrainz-mcp

Category: Tools & Productivity | Uploader: serjflint | Downloads: 0 | Version: v1.0（Latest）

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.

Changelog: Source: GitHub https://github.com/serjflint/listenbrainz-mcp

Directory Structure

Current level: Root

📁 scripts/
- 📄 split_models.py 5.3 KB
📁 src/
- 📁 listenbrainz_mcp/
  - 📁 models/
    
    📁 gen/
    
    📄 __init__.py 0 B
    
    📄 feedback.py 2.2 KB
    
    📄 listens.py 3.3 KB
    
    📄 metadata.py 2.0 KB
    
    📄 playlists.py 1.0 KB
    
    📄 popularity.py 2.7 KB
    
    📄 recommendations.py 1.3 KB
    
    📄 shared.py 11.1 KB
    
    📄 social.py 2.5 KB
    
    📄 stats.py 10.6 KB
    
    📄 utility.py 5.8 KB
    
    📄 __init__.py 50 B
    
    📄 feedback.py 1.1 KB
    
    📄 listens.py 2.4 KB
    
    📄 metadata.py 6.3 KB
    
    📄 popularity.py 2.2 KB
    
    📄 shared.py 5.0 KB
    
    📄 similar.py 521 B
    
    📄 stats.py 3.8 KB
    
    📄 utility.py 464 B
  - 📁 tools/
    
    📄 __init__.py 30 B
    
    📄 feedback.py 1.7 KB
    
    📄 listens.py 4.1 KB
    
    📄 metadata.py 4.6 KB
    
    📄 popularity.py 3.0 KB
    
    📄 stats.py 6.2 KB
  - 📄 __init__.py 31 B
  - 📄 __main__.py 955 B
  - 📄 client.py 6.7 KB
  - 📄 py.typed 0 B
  - 📄 retry.py 1.0 KB
  - 📄 server.py 3.4 KB
📁 tests/
- 📁 tools/
  - 📄 __init__.py 18 B
  - 📄 test_feedback.py 1.6 KB
  - 📄 test_listens.py 17.2 KB
  - 📄 test_metadata.py 11.0 KB
  - 📄 test_popularity.py 4.9 KB
  - 📄 test_stats.py 6.7 KB
- 📄 __init__.py 29 B
- 📄 conftest.py 1.4 KB
- 📄 test_models.py 4.2 KB
📄 .coverage 52.0 KB
📄 .gitignore 112 B
📄 .python-version 5 B
📄 AGENTS.md 3.1 KB
📄 LICENSE 1.1 KB
📄 Makefile 1.0 KB
📄 pyproject.toml 3.3 KB
📄 README.md 9.7 KB
📄 research_class_mapping.json 24.3 KB
📄 SKILL.md 4.8 KB
📄 uv.lock 316.1 KB

SKILL.md

---
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:
   ```bash
   git clone https://github.com/serjflint/listenbrainz-mcp
   cd listenbrainz-mcp
   uv sync
   ```

2. Copy the skill to your agent skills directory:
   ```bash
   mkdir -p ~/.agents/skills/listenbrainz-mcp
   cp skill/SKILL.md ~/.agents/skills/listenbrainz-mcp/SKILL.md
   ```

3. Verify installation:
   ```bash
   listenbrainz-mcp --help
   ```

## MCP Configuration

Add to your MCP settings JSON:

```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

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

listenbrainz-mcp

Directory Structure

SKILL.md

Report

Notice