discord-music-mcp

An MCP server that lets Claude (or any MCP client) play music in your Discord voice channel.

"Play some lo-fi in the Lobby" → 🎶

📚 Learning MCP? This repo is also a commented, step-by-step tutorial (Turkish): docs/TUTORIAL.tr.md.

How it relates to Discord YouTube DJ

This repo is not a Discord bot. It's a small adapter in front of Discord YouTube DJ, the self-hosted bot that does the actual work.

 ┌──────────────────┐  stdio (JSON-RPC)  ┌──────────────────┐  HTTP 127.0.0.1:1231  ┌──────────────────────┐        ┌─────────┐
 │ Claude Desktop / │ ─────────────────► │ discord-music-mcp│ ────────────────────► │ Discord YouTube DJ   │ ─────► │ Discord │
 │ Claude Code      │ ◄───────────────── │ (this repo)      │ ◄──────────────────── │ bot (other repo)     │  voice │         │
 └──────────────────┘                    └──────────────────┘                       └──────────────────────┘        └─────────┘

• Claude starts this server as a child process when it needs it. You don't run it yourself.

• This server turns tool calls (play_song, stop_music, …) into requests to the bot's local API.

• The bot holds the Discord token and joins voice channels. This repo never sees or needs your Discord token.

• Because the bot only accepts connections from 127.0.0.1, this server must run on the same computer as the bot.

Related MCP server: YouTube Search & Download MCP Server

What you need

Not needed: no Discord token, no client secret, no API keys, no server or channel IDs. You refer to channels by name ("Lobby"). Channel IDs also work: enable Discord Settings → Advanced → Developer Mode, then right-click a channel → Copy Channel ID.

Setup

1. Get the code

git clone https://github.com/cengizhanpece/discord-music-mcp
cd discord-music-mcp
npm install

Note the full path of src/index.js. You'll need it below, e.g. C:\Users\you\discord-music-mcp\src\index.js or /home/you/discord-music-mcp/src/index.js.

2. Check that it can reach the bot

npm test

You should see the list of tools followed by your voice channels. If you see "Could not reach the Discord YouTube DJ bot", start the bot first.

3. Connect it to your MCP client

Claude Code:

claude mcp add discord-music -- node "C:\full\path\to\discord-music-mcp\src\index.js"

Then run /mcp inside Claude Code to confirm it's connected.

Claude Desktop: open Settings → Developer → Edit Config (this opens claude_desktop_config.json) and add:

{
  "mcpServers": {
    "discord-music": {
      "command": "node",
      "args": ["C:\\full\\path\\to\\discord-music-mcp\\src\\index.js"]
    }
  }
}

On Windows, write the path with double backslashes (\\) as shown. Fully quit Claude Desktop (including the tray icon) and reopen it.

Non-default bot port: if you changed the bot's port, add the address to the config. MCP clients don't pass your terminal's environment variables to the server, so it has to go in the config:

claude mcp add discord-music -e MUSIC_BOT_URL=http://localhost:4000 -- node "C:\full\path\to\discord-music-mcp\src\index.js"

"discord-music": {
  "command": "node",
  "args": ["C:\\full\\path\\to\\discord-music-mcp\\src\\index.js"],
  "env": { "MUSIC_BOT_URL": "http://localhost:4000" }
}

4. Try it

"Which voice channels can you play in?" "Play Daft Punk – Get Lucky in the Lobby." "Search for three versions of Kuzu Kuzu and let me pick." "What's playing?" / "Stop the music."

Updating

cd discord-music-mcp
git pull
npm install

Restart Claude Desktop, or run /mcp → reconnect in Claude Code.

What it can do

Also: resource discord://voice-channels and prompt dj ("pick something that fits a mood and play it").

Troubleshooting

Development

node scripts/test-client.js search "daft punk"     # a ~40-line MCP client, see how a host talks to the server
node scripts/test-client.js play "daft punk get lucky"
npm run inspect                                     # MCP Inspector UI

Logs go to stderr. stdout is reserved for the JSON-RPC stream.

License

MIT