Metadata-Version: 2.4
Name: plyrfm-mcp
Version: 0.0.1a18
Summary: MCP server for plyr.fm
Author-email: zzstoatzz <thrast36@gmail.com>
License-Expression: MIT
Keywords: atproto,mcp,music,plyr,streaming
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0
Requires-Dist: jmespath>=1.0
Requires-Dist: plyrfm==0.0.1a18
Description-Content-Type: text/markdown

# plyrfm-mcp

MCP server for [plyr.fm](https://plyr.fm) - expose your music library to LLM clients.

## quickstart

use the hosted server with claude code:

```bash
claude mcp add-json plyr-fm '{"type": "http", "url": "https://plyrfm.fastmcp.app/mcp", "headers": {"x-plyr-token": "YOUR_TOKEN"}}'
```

or run locally via uvx:

```bash
PLYR_TOKEN="your_token" uvx plyrfm-mcp
```

## install

```bash
uv add plyrfm-mcp
```

## tools

this server is **read-only** by design. use the `plyrfm` CLI for mutations (upload, delete, like, unlike).

**public (no auth):**
- `list_tracks` - list public tracks
- `get_track` - get a single track by ID
- `search` - search tracks, artists, albums, tags
- `top_tracks` - get top tracks by likes
- `list_tags` - list all tags with track counts
- `tracks_by_tag` - get tracks with a specific tag

**authenticated:**
- `my_tracks` - list your tracks
- `liked_tracks` - list your liked tracks

tools that return lists support `_filter` for jmespath filtering.

## filtering

tools that return lists support a `_filter` parameter for jmespath expressions:

```
# select specific fields
list_tracks(_filter="[*].{id: id, title: title}")

# filter by condition
list_tracks(_filter="[?play_count > `50`]")

# extract values
list_tracks(_filter="[*].title")
```

## auth

get a developer token at [plyr.fm/portal](https://plyr.fm/portal) -> "developer tokens"
