MPD MCP for Node.js

A small MCP server that lets ChatGPT and other MCP clients control a Music Player Daemon (MPD) server. Plain JavaScript on Node.js 22 or later; no build step, OpenAI SDK, or OpenAI API key is required by this server.

Run

npm install
npm start

The Streamable HTTP MCP endpoint is http://127.0.0.1:3000/mcp. It controls MPD at 127.0.0.1:6600 by default. MPD must already be installed, running, and configured with a music library and audio output. This application sends controls to MPD; audio plays through MPD's output, not inside ChatGPT.

The server connects to MPD when a tool is called, so MCP discovery works even if MPD is offline. Use mpd_status to check the connection. Use a modern MPD release (0.21 or later recommended).

Configuration

Edit config.json, or create an ignored config.local.json with just your overrides:

{
  "mpd": {
    "host": "192.168.1.50",
    "port": 6600
  }
}

Select the override file explicitly and supply an optional MPD password through the environment. PowerShell:

$env:MPD_MCP_CONFIG = "$PWD/config.local.json"
$env:MPD_PASSWORD = "your-mpd-password"
npm start

Bash:

MPD_MCP_CONFIG=./config.local.json MPD_PASSWORD=your-mpd-password npm start

Precedence: config.json defaults → selected override file → environment variables. The default file resolves relative to the application, independently of the working directory. A relative override path resolves from the working directory. Restart after changing configuration. Unknown keys and invalid values cause startup to fail.

Setting	Default	Environment override
mpd.host	127.0.0.1	MPD_HOST
mpd.port	6600	MPD_PORT
mpd.password	Empty (no authentication)	MPD_PASSWORD
mpd.timeoutMs	5000	MPD_TIMEOUT_MS
mpd.maxResponseBytes	4194304 (4 MiB per operation)	Configuration file only
server.transport	http	MCP_TRANSPORT (http or stdio)
server.host	127.0.0.1	MCP_HOST
server.port	3000	MCP_PORT
server.path	/mcp	Configuration file only
server.allowedHosts	localhost, 127.0.0.1, [::1]	Configuration file only
server.allowedOrigins	[]	Configuration file only

allowedHosts contains hostnames without ports. Requests carrying an Origin header are rejected unless that exact origin is listed in allowedOrigins; requests without that header are accepted. This is origin validation, not browser CORS support. MPD passwords authenticate this application to MPD, not MCP clients to this application. Keep passwords out of committed files.

Connect ChatGPT

ChatGPT needs an MCP endpoint reachable through HTTPS or a Secure MCP Tunnel; its hosted service cannot reach your machine's localhost directly. See OpenAI's connection guide and Secure MCP Tunnel guide.

For a private MPD installation:

1. Start this server with npm start and follow the Secure MCP Tunnel guide to provision a tunnel associated with your ChatGPT workspace. Configure the tunnel client to reach http://127.0.0.1:3000/mcp.
2. Enable developer mode in ChatGPT under Settings → Security and login (availability depends on your account/workspace).
3. Add an MCP connection from ChatGPT Plugins, choose Tunnel, and select your tunnel or enter its ID.
4. Review the discovered tools, enable the connection in a conversation, and ask “What is playing?” or “Set the music volume to 35.”

The basic server does not implement OAuth or inbound authentication. Keep it private using the authenticated tunnel. Public deployment requires an authentication gateway compatible with your MCP client, such as OAuth for ChatGPT, and HTTPS. If using a reverse proxy, add its incoming hostname to server.allowedHosts or have it rewrite Host to the local upstream; a host allowlist is not authentication. Do not expose the MPD TCP port to the public internet.

Local MCP clients (stdio)

npm run start:stdio

For a client that starts MCP subprocesses, adapt this configuration with absolute paths:

{
  "mcpServers": {
    "mpd": {
      "command": "node",
      "args": ["C:/path/to/MPD MPC/src/index.js", "--stdio"],
      "env": {
        "MPD_HOST": "192.168.1.50",
        "MPD_PORT": "6600"
      }
    }
  }
}

--stdio overrides the configured transport. Launch node directly from MCP clients so npm's own output cannot interfere with protocol messages. Application logs go to stderr.

Tools

Tool	Arguments	Action
mpd_status	None	Playback state, volume/options and current song
mpd_play	Optional songId	Play/resume, or play a queue entry by stable ID
mpd_pause / mpd_resume	None	Explicitly pause/resume without toggling
mpd_stop	None	Stop playback
mpd_next / mpd_previous	None	Skip between tracks
mpd_set_volume	volume: integer 0–100	Set mixer volume
mpd_seek	seconds: nonnegative number	Absolute seek within the current track
mpd_set_repeat / mpd_set_random	enabled: boolean	Change playback options
mpd_queue	offset = 0, limit = 50	Read a page of queued songs
mpd_search	query, tag = any, offset = 0, limit = 50	Search library metadata
mpd_add	uri	Add a file or stream URI; returns its Id
mpd_remove	songId	Remove one queued song
mpd_clear_queue	None	Empty the queue and stop playback

Search tags: any, artist, album, title, filename. Page limits are 1–200. Offsets and queue positions start at zero. IDs are stable while a song is queued; pass them as integers to tools. Clearing/removing queue entries never deletes files. Adding does not automatically start playback.

Typical sequence: search → add a returned file → play the returned Id. Metadata retains MPD's field names and string values; repeated tags become arrays. Successful results include text JSON and structured content. MPD errors are returned with MCP isError: true.

Volume needs a configured MPD mixer. Stream playback needs the corresponding MPD input/decoder support. Search uses MPD result windows. TCP disconnects, authentication errors, timeouts, and oversized replies fail the operation; mutations are never automatically retried because a lost response may follow an already executed command. A new call opens a fresh MPD connection.

Verify

npm test
npx @modelcontextprotocol/inspector

In Inspector, choose Streamable HTTP and connect to http://127.0.0.1:3000/mcp. Tests use a simulated MPD TCP server and the official MCP client to exercise HTTP and stdio initialization, all controls, input validation, authentication, fragmented replies, concurrent operations and failure recovery. No live MPD server is needed for tests.

Protocol references: MPD protocol, MCP SDK server guide.