thrash.dev

docs / providers / mcp server

Providers · chapters · 24 of 25

← Yafmp manual

  1. Local Files
  2. Plex
  3. Navidrome
  4. Jellyfin
  5. Bandcamp
  6. Lidarr
  7. Apple Music
  8. Spotify
  9. SoundCloud
  10. YouTube Music
  11. SiriusXM
  12. Radio
  13. Podcasts
  14. AirPlay
  15. Chromecast
  16. MusicBrainz
  17. Discogs
  18. Labels
  19. Releases
  20. Last.fm
  21. ListenBrainz
  22. Connect
  23. Home Assistant
  24. MCP server
  25. DJ

MCP server

A local MCP server that lets AI apps see what is playing and control the player.

facts

status
stable
kind
control
on by default
yes
needs
An MCP client on the same computer
platforms
Linux, FreeBSD, Windows

Description

The MCP server lets an AI app control Yafmp through the Model Context Protocol. It exists in the desktop edition only.

An MCP client on the same computer can see what is playing, search and browse the library, play, manage the queue and run any command from the command palette, such as picking an AirPlay speaker or an equalizer preset. It can also ask the DJ for a playlist.

The server offers these tools:

ToolWhat it does
get_statusWhat is playing: state, track, position, output, volume, shuffle, repeat and the queue’s length.
play, pause, stopResume (or start the queue from the top), pause, or stop. Stop keeps the queue.
next, previousSkip to the next or previous track.
seekJump to a position in the current track, in seconds.
set_volumeSet the volume, 0 to 100, of this computer or of the AirPlay or Cast speaker.
set_shuffle, set_repeatShuffle on or off; repeat off, all or one.
searchSearch the library sources for artists, albums, songs and stations.
browseWalk the library tree: the sources, a source’s top rows, then their contents.
play_itemPlay a search or browse result. An album, artist, playlist or folder plays whole.
add_to_queueAdd a result’s tracks to the end of the queue without playing.
get_queueThe queue, numbered from 1, with the playing track marked.
play_queue_numberPlay the track with that number in the queue.
remove_from_queueRemove tracks from the queue by number.
clear_queueStop and empty the queue.
list_commandsThe app’s palette commands, with their ids.
run_commandRun a palette command by id, with its text when it takes one.
djAsk the DJ for music. It picks tracks from the library and plays them.

Requirements

  • Yafmp for Linux, FreeBSD or Windows, running.
  • An MCP client on the same computer that supports the Streamable HTTP transport.

Setup

  1. Open Settings → MCP server. The switch Let AI apps control Yafmp is on by default, and the line under it reads “Listening on http://127.0.0.1:43823/mcp”.

  2. Add the server to your MCP client with these details:

    TransportStreamable HTTP
    URLhttp://127.0.0.1:43823/mcp
    Authenticationnone
  3. For Claude Code, the settings pane shows the command to copy:

    claude mcp add --transport http yafmp http://127.0.0.1:43823/mcp
    

Settings

SettingDefaultWhat it does
Let AI apps control YafmponStarts or stops the server.

Under the switch, a status line shows the address the server listens on, Off, or why it could not start. The pane also shows the Claude Code command with the address filled in.

Limits

  • Desktop edition only. Not on Android or in the Apple edition.
  • The server listens on this computer only (127.0.0.1). It cannot be reached from another machine.
  • There is no password or token. Any program running under your user account can use it, as with the media keys.
  • Requests from a web page are refused: the request’s Host, and its Origin when there is one, must be this machine.
  • The server answers POST requests with plain JSON. It opens no server-to-client stream and keeps no sessions.
  • The dj tool only starts the DJ. The playlist arrives later; the client has to ask for the status again.

Troubleshooting

ProblemWhyWhat to do
The status line says “Couldn’t listen on port 43823”Another program, or a second copy of Yafmp, already uses the portQuit the other program, then switch the server off and on.
The client gets “405 Method Not Allowed”It sent a GET, as the older SSE transport doesSet the client’s transport to Streamable HTTP.
The client gets “403 Forbidden”The request named a host other than this machineUse 127.0.0.1 or localhost in the URL.
The dj tool answers “The DJ is switched off”The DJ plugin is disabledSwitch DJ on in Settings and set its model.