listenbrainz-mcp

Self-hosted MCP server exposing the full public ListenBrainz API as 37 tools over stdio: 94/94 OpenAPI spec operations plus 35 documented-but-not-in-spec endpoints (129 total), enforced by an exact-set coverage gate in the test suite.

Python ≥ 3.11 · mcp 2.x SDK · httpx2. Tools return JSON envelope strings — failures are {"error": ..., "status": ...} envelopes, never raises. The LISTENBRAINZ_TOKEN, if set, only ever rides the Authorization header: never logged, never echoed into an envelope.

Install & run

python -m venv .venv
.venv/bin/pip install -e ".[dev]"    # runtime + pytest
.venv/bin/listenbrainz-mcp           # stdio server; or: python -m listenbrainz_mcp

Related MCP server: musicbrainz-mcp-server

Configuration

Register with any MCP client using the common config shape:

{
  "mcpServers": {
    "listenbrainz": {
      "command": "/absolute/path/to/listenbrainz-mcp/.venv/bin/listenbrainz-mcp",
      "args": [],
      "env": { "LISTENBRAINZ_TOKEN": "<token, or omit>" }
    }
  }
}

Tools

Full per-tool endpoint map lives in the registry itself — import listenbrainz_mcp.server and read coverage.snapshot() (or run each tool's docstring, which carries the authoritative usage notes):

Five spec paths differ live (spec spelling 404s); the real paths are wired and documented in coverage.SANCTIONED_SPEC_OVERRIDES.

Timeouts & upstream quirks

Default client timeout is 30 s; three slow routes ride per-request overrides, each asserted at the transport seam by unit tests:

• lb-radio generation routes (explore/lb-radio, lb-radio/artist/{mbid}, lb-radio/tags) → 120 s (generation observed ~28–40 s)

• GET /1/playlist/search → 90 s (upstream answers in ~32–33 s consistently)

• GET /1/donors/all-flairs → 60 s (~25 s observed)

Upstream occasionally resets long-running connections at ~40 s on /1/lb-radio/tags (RemoteProtocolError envelope). It is server-side and intermittent — retry before assuming a code fault.

Testing

.venv/bin/pytest tests/ -q

Gates: exact-set coverage (every spec op claimed exactly once), domain unit tests on a scripted transport, and full in-process dispatch tests (real MCP client → MCPServer → impls → LBClient with a faked socket). scripts/live_smoke.py is a manual seven-call unauthenticated smoke against the real API.

License

0BSD — Zero-Clause BSD.