title: "for developers" description: "build on plyr.fm — API, lexicons, and architecture"#

plyr.fm exposes a public API, a Python SDK, and an MCP server. build players, analytics, recommendation engines, or integrations on top of the open data.

API#

the full OpenAPI spec is at api.plyr.fm/docs. key endpoints:

authenticated endpoints require a developer token from plyr.fm/portal.

Python SDK#

uv add plyrfm

from plyrfm import PlyrClient

client = PlyrClient()

# list tracks
for track in client.list_tracks(limit=5):
    print(f"{track.id}: {track.title} by {track.artist}")

# get a specific track
track = client.get_track(42)

authenticated operations (upload, download, manage your tracks) require a token:

client = PlyrClient(token="your_token")
my_tracks = client.my_tracks()
client.upload("song.mp3", "My Song")

see the plyr-python-client repo for full docs.

MCP server#

the plyrfm-mcp package provides an MCP server for AI assistants:

uv add plyrfm-mcp

add to Claude Code:

claude mcp add plyr-fm -- uvx plyrfm-mcp

tools include search, list_tracks, top_tracks, tracks_by_tag, and more. see the repo for setup options.

developer tokens#

generate tokens at plyr.fm/portal. tokens are scoped to your account and can be revoked at any time.

ATProto lexicons#

all plyr.fm data uses custom ATProto lexicons under the fm.plyr namespace. see the lexicons overview for schemas and record types.

contributing#

plyr.fm is open source. see the contributing guide to get involved.