local-music-mcp-server

olivelb/local-music-mcp-server

3.1

If you are the rightful owner of local-music-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Music MCP Server is a Model Context Protocol server designed for managing music libraries and controlling Chromecast playback, optimized for integration with LM Studio.

Tools
21
Resources
0
Prompts
0

🎵 Music MCP Server

A Model Context Protocol (MCP) Server for music library management and Chromecast playbook control, optimized for LM Studio integration.

✨ Key Features

  • 🎯 21 Music Tools - Complete control over music playback and library
  • 📡 Chromecast Integration - Native Google Cast queue support
  • ⚡ Ultra-Fast Responses - No timeout issues with LM Studio (~20ms)
  • 🔄 Persistent Operation - Background server survives disconnections
  • 📚 Large Library Support - Tested with 13,294+ tracks

🚀 Quick Start

1. Installation

git clone <repository>
cd music-mcp-server
npm install

2. Configure LM Studio

Add to your LM Studio MCP configuration:

{
  "mcpServers": {
    "music": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["lm-studio.js"],
      "cwd": "D:/mcp-server/music-mcp-server",
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "error"
      },
      "timeout": 30000
    }
  }
}

3. Start Using

  1. Start server: start_music_server()
  2. Find devices: list_chromecasts()
  3. Search music: search_music({"query": "artist name"})
  4. Play tracks: play_multiple_tracks({"tracks": [1,2,3], "device_name": "device"})

🚀 Alternative: NPM Scripts

You can also run the interface using npm scripts:

# Start LM Studio interface
npm run lm-studio

# Start persistent server
npm run server

# Start server in background
npm run server:background

# Development mode
npm run dev

🛠️ Available Tools

Server Management (3)

  • start_music_server - Start background server
  • stop_music_server - Stop background server
  • server_status - Check server health

Chromecast Control (3)

  • list_chromecasts - Discover devices
  • connect_chromecast - Connect to device
  • get_chromecast_status - Get connection status

Music Library (2)

  • search_music - Search tracks (supports fuzzy, exact matching)
  • get_library_stats - Library statistics

Playback (6)

  • play_track - Play single track
  • play_multiple_tracks - Play queue with native Cast support
  • pause_playback / resume_playbook / stop_playbook - Playbook control
  • get_playlist_status - Current playbook info

Navigation (4)

  • skip_to_next / skip_to_previous - Skip tracks
  • skip_to_track - Jump to specific track number
  • seek_to_position - Seek within track

Queue & Volume (3)

  • manage_queue - Add/remove/shuffle/repeat queue
  • set_volume - Volume control (0.0-1.0)
  • manage_playlist - Create/manage playlists

📁 Project Structure

music-mcp-server/
├── lm-studio.js                      # Main LM Studio interface (renamed)
├── persistent-music-server.js        # Background music server
├── lm_studio_config_node.json       # LM Studio configuration
├── src/                              # Core application code
│   ├── controllers/                  # Music & Chromecast controllers
│   ├── services/                     # Database & Chromecast services
│   └── utils/                        # Utilities & validation
├── data/                             # Database & state files
├── docs/                             # API documentation
└── scripts/                          # Utility scripts

🔧 Architecture

Two-Component Design

  1. lm-studio.js - Ultra-fast MCP interface for LM Studio (renamed for simplicity)
  2. persistent-music-server.js - Background server for music operations

Why This Works

  • No Timeouts: Protocol methods respond instantly
  • Persistent State: Music server runs independently
  • Automatic Management: Server starts/stops as needed
  • Error Recovery: Robust error handling and reconnection

🎵 Supported Audio Formats

  • MP3, FLAC, WAV, AAC, M4A, OGG, WMA
  • Full ID3 metadata support
  • Automatic content-type detection

📊 Performance

  • Library Size: 13,294+ tracks tested
  • Response Time: ~20ms for protocol methods
  • Memory Usage: Optimized for large libraries
  • Network: Efficient Chromecast streaming

🔍 Troubleshooting

Common Issues

  1. Tools not loading: Restart LM Studio after config changes
  2. Server not starting: Check port 8765 availability
  3. Chromecast not found: Ensure devices on same network
  4. Playback stops: Check Chromecast connection stability

Logs

  • Server logs: data/music-server.log
  • Check server status: server_status() tool

📄 License

MIT License - See LICENSE file for details

Ready for production use with LM Studio! 🎵