@freeyourmusic/mcp

MCP (Model Context Protocol) server that exposes Free Your Music to AI agents. Stdio transport — runs as a subprocess managed by an MCP host (Claude Desktop, Cursor, Cline, Claude Code, etc.).

Requires Free Your Music desktop running. See @freeyourmusic/cli for the wire format.

Maintainers: the version is copied from renderer/package.json and the package is published from the master-desktop pipeline (ci/fym-mcp/publish.sh). On a desktop app that runs the server data path (Realm exit), the playlist, library, search and write tools answer UNSUPPORTED_OPERATION.

Install for an MCP host

# Claude Desktop
npx -y @freeyourmusic/mcp install --host=claude-desktop
# Claude Code
npx -y @freeyourmusic/mcp install --host=claude-code
# Cursor
npx -y @freeyourmusic/mcp install --host=cursor
# Cline
npx -y @freeyourmusic/mcp install --host=cline
# Print the JSON snippet (manual install)
npx -y @freeyourmusic/mcp install --host=print

Then restart the host. The tools appear under the freeyourmusic server.

Tool catalog (v1)

Read (free): fym_status, fym_services, fym_accounts, fym_login, fym_playlists_list, fym_playlists_get, fym_tracks_list, fym_library_tracks, fym_library_albums, fym_library_artists, fym_history_recent

Search (free with 100/day quota): fym_search_tracks, fym_search_albums, fym_search_artists

Write (Pro): fym_playlists_create, fym_playlists_rename, fym_playlists_delete, fym_tracks_add, fym_tracks_remove, fym_tracks_reorder, fym_library_like, fym_library_unlike, fym_follow_artist, fym_unfollow_artist

When a service has two or more connected accounts, pass account (an id or a label) to pick one.

Privacy

No telemetry added. All traffic to the bridge is 127.0.0.1. The bearer token rotates on every desktop launch.

Error reporting

Published builds report unexpected failures to FreeYourMusic's Sentry project. Tool arguments, bridge credentials, request payloads and Redux state are not attached. Development/test builds do not report. Set FYM_DISABLE_TELEMETRY=1 to disable reporting, or SENTRY_DSN to use your own destination. MCP protocol output remains on stdout; diagnostic output uses stderr.