Fidelia

Search and play the music you own in Fidelia, an audiophile music player for Mac, from Claude, Codex or any MCP app.

Documentation

Fidelia MCP server

Fidelia

Play and explore the music you own in Fidelia, an audiophile music player for Mac, from Claude, Codex or any MCP app.

Ask for music the way you'd ask a friend who knows your records: "play some irish trad", "put on that album I got yesterday", "something by Planxty". Fidelia finds it in the music you own (your files, your Music library and any servers you've added) and plays it: a record in track order, a genre or an artist shuffled. When the tags say less than you mean, "Folk" where you mean Irish traditional music, your AI app reads your genres, artists and composers and uses what it knows about the music to choose.

The server is part of Fidelia itself. This repository holds what an AI app needs to reach it: a Claude Desktop extension, a Claude Code plugin, and the setup for other MCP apps.

What your AI app can and can't do

It can read your whole Fidelia library (titles, artists, albums, genres, composers, years, when you added each one, your playlists, your radio stations and what's playing), play, queue, pause and skip, set the volume, shuffle and repeat, and make playlists or add to them.

It never learns where your files are, and it can't change or delete them. What it reads goes to your AI app's service, under that app's terms.

What you need

  • Fidelia for Mac 2.13 or later, on macOS 14 or later.
  • Fidelia ▸ Settings ▸ Agent ▸ Let AI apps use Fidelia turned on. It's off until you turn it on, and the same page shows your token.
  • Playing music needs Fidelia's one-time unlock or its free trial, as it does in the app; music from a server also needs the Network & Server unlock. Reading the library, pausing, the volume and playlists work without them.

Set it up

Claude

In Fidelia, open Settings ▸ Agent and click Make Extension…. Fidelia saves the extension with your token inside and opens it in Claude, which asks to install it.

Or download Fidelia.mcpb from the latest release, open it, and paste the token from Fidelia's Settings ▸ Agent when Claude asks for it.

When Fidelia isn't running, the extension opens it with no window, so asking Claude for music starts it.

Claude Code

Add this repository as a plugin marketplace and install the plugin. Claude Code asks for the token from Fidelia's Settings ▸ Agent and for Fidelia's port (keep 38412 unless you changed it there). The plugin runs the same bridge as the Claude extension, so it needs Node.js on your PATH:

/plugin install fidelia --marketplace weareaudiofile/fidelia-mcp

On Claude Code before 2.1.275, add the marketplace first:

/plugin marketplace add weareaudiofile/fidelia-mcp
/plugin install fidelia@fidelia-mcp

Or run one line in Terminal; Settings ▸ Agent shows it with your token already in it:

claude mcp add --transport http fidelia http://127.0.0.1:38412/mcp --header "Authorization: Bearer YOUR_TOKEN"

Codex

Add this to ~/.codex/config.toml, then restart Codex. Settings ▸ Agent shows it with your token already in it:

[mcp_servers.fidelia]
url = "http://127.0.0.1:38412/mcp"
http_headers = { "Authorization" = "Bearer YOUR_TOKEN" }

Other MCP apps

Fidelia serves Streamable HTTP at http://127.0.0.1:38412/mcp and wants the header Authorization: Bearer YOUR_TOKEN. In an app that takes an mcpServers JSON file:

{
  "mcpServers": {
    "fidelia": {
      "url": "http://127.0.0.1:38412/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

If you change the port in Settings ▸ Agent, change it here too.

Things to ask

  • "Play some irish trad."
  • "Put on the album I got yesterday."
  • "Queue that Bothy Band record next."
  • "What's playing?"
  • "Make a playlist of everything I added last month."
  • "What's the oldest piece I own, by when it was written? Play it."
  • "Play one of my radio stations."

Tools

ToolWhat it does
searchSearch the libraryreads
genresList genresreads
artistsList artistsreads
composersList composersreads
artists_in_genreList a genre's artistsreads
recently_addedList recently added albumsreads
album_tracksList an album's tracksreads
now_playingWhat's playingreads
stationsList radio stationsreads
playlistsList playlistsreads
playlist_tracksList a playlist's tracksreads
playPlayacts
queueAdd to the queueacts
pausePauseacts
transportResume or skipacts
set_volumeSet the volumeacts
set_shuffleShuffle on or offacts
set_repeatSet repeatacts
make_playlistMake a playlistacts
add_to_playlistAdd to a playlistacts

Lists come in pages, because a library can run to 100,000 tracks. A page of tracks is grouped by album.

What's in this repository

  • plugins/fidelia/: the Claude Code plugin. It runs its own copy of server/index.js (below) with Node.js, with Fidelia's port and your token from its settings.
  • server/index.js: the script inside Fidelia.mcpb, which Claude runs with its own Node. It hands each message to Fidelia at 127.0.0.1 with your token and writes back Fidelia's answer. When nothing answers, it opens Fidelia with no window (open -g -b com.audiofile.fidelia --args -agent.headless YES) and tries again for up to 45 seconds. It uses only Node's own modules.
  • server.json: Fidelia's entry in the official MCP Registry.
  • tools/publish_listing.py and tools/listing.json: how Fidelia's own CI keeps this repository, its releases and its registry entry equal to what Fidelia serves. When a Fidelia release changes its tools, the script writes them here from Fidelia itself, releases the new Fidelia.mcpb and publishes the new version to the registry. People never run it.
  • glama/, Dockerfile and glama.json: for Glama's automated build check only. Fidelia's server is part of the Fidelia app, so Glama's Linux build machine runs server/index.js against a stand-in that lists Fidelia's real tools (glama/tools.json, read from Fidelia itself) and answers every call with a note to install Fidelia. People never run these files.

Privacy and security

  • Fidelia listens on 127.0.0.1 only. Nothing on your network or the internet can reach it.
  • Only an app with the token from Settings ▸ Agent can connect. New Token there turns the old one away at once. A request from a web page is refused.
  • The server answers only the AI app you set up. That app sends what it reads to its own AI service, under that app's terms.
  • Audiofile's privacy policy: https://audiofile.engineering/privacy

Support

Questions and problems: https://audiofile.engineering/support

License

The files in this repository are under the MIT License. Fidelia itself is Audiofile Engineering's app, on the Mac App Store.