Tubist Server

Remember the last time when you closed a tab or quit your browser and YouTube audio abruptly stopped...? Bet you were angry.

Tubist exists for that not to happen. It's a lightweight macOS menu bar player that keeps YouTube going independently of your browser.

Tubist is available for free on the Mac App Store.

This MCP server lets Claude and other AI assistans control Tubist when asked to do so from the assistant's macOS app.

Just ask naturally:

• play the Billie Eilish Tiny Desk concert
• find me some jazz on YouTube for focus and play it in Tubist
• look for an orchestral rendering of Super Mario music on YouTube and play it in Tubist

Features

• 🎬 Play any YouTube video with a simple request... (unless it longer exists 😞)
• 🎵 Ideal for background audio (concerts, podcasts, music)
• 🤖 Control via natural language through AI assistants
• ⚡ Instant playback - just ask and it plays without any UI interruptions

Prerequisites / minimum requirements

• macOS 13 (Ventura) and above
• Tubist v1.3 installed (Tubist is available for free on the Mac App Store.)
• Node.js 18.0.0 or higher
• Claude Desktop or another MCP-compatible client

Installation

1. Clone this repository:

   git clone https://github.com/dkasaj/tubist-mcp-server.git
   cd tubist-mcp-server
   

2. Install dependencies:

   npm install
   

3. Configure Claude Desktop:

   Edit your Claude Desktop config file:

   # On macOS
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

   Add the Tubist MCP server, use the path where you installed it:

   {
     "mcpServers": {
       "Tubist - menu bar player for YouTube": {
         "command": "/opt/homebrew/bin/node",
         "args": ["/path/to/tubist-mcp-server/index.js"]
       }
     }
   }
   

   Important: Replace /path/to/tubist-mcp/index.js with the actual path where you cloned this repo.

   Find your Node.js path:

   which node
   

   Use this path instead of /opt/homebrew/bin/node if different.

4. Restart Claude Desktop completely (quit and reopen, don't just close the window)

Usage

Once configured, you can ask Claude to play YouTube videos naturally:

Examples:

• "Play the Billie Eilish Tiny Desk concert"
• "Find me some jazz on YouTube for focus and play it in Tubist"
• "Look for an orchestral rendering of Super Mario music on YouTube and play it in Tubist"

How It Works

1. You make a request to Claude
2. Claude uses the MCP protocol to call this server
3. The server opens the YouTube video in Tubist using the tubist://play? URL scheme
4. Video starts playing automatically

Troubleshooting

"MCP server disconnected" error

• Check that the path in claude_desktop_config.json is correct
• Verify Node.js path with which node
• Make sure you restarted Claude Desktop completely

Video doesn't play

• Ensure Tubist is installed and can be launched
• Try opening Tubist manually first to verify it works
• Check that the YouTube URL is valid. Claude for instance sometimes uses a link to a video that no longer exists.

Tool doesn't appear in Claude

• Confirm the config file is valid JSON (use a JSON validator)
• Check for log Claude Desktop logs: ~/Library/Logs/Claude/
• Make sure you saved the config file and restarted Claude

Technical Details

This MCP server uses the Server class with setRequestHandler pattern (rather than McpServer.tool()) due to a known bug in MCP SDK 1.25.x where arguments aren't passed correctly to tool handlers.

Tool definition:

• Name: play
• Parameter: url (YouTube video URL)
• Action: Opens video in Tubist via tubist://play?[url] URL scheme

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

License

MIT © Daniel Kašaj

Links

• Tubist on the Mac App Store
• Model Context Protocol Documentation
• Claude Desktop

---

Made with ❤️ for background YouTube listening