A Model Context Protocol (MCP) server that enables Google Gemini CLI to control Spotify through natural language commands.

• Play Control: Play playlists, albums, and tracks
• Search: Find music by song, artist, or album
• Playback Control: Play, pause, skip, and adjust volume
• Sleep Timer: Automatically pause playback after a specified duration

• Node.js 18+
• npm or yarn
• Spotify Developer account
• Google Gemini CLI installed (npm install -g @google/gemini-cli)

npm install
npm run build

1. Go to Spotify Developer Dashboard
2. Create a new app
3. Copy your Client ID and Client Secret
4. Click "Edit Settings" → Add redirect URI: http://127.0.0.1:3000/callback
5. Click "Save"

Important: Spotify requires 127.0.0.1 (not localhost) for redirect URIs.

Create a .env file in the project root:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://127.0.0.1:3000/callback

npm run auth

This opens your browser for Spotify authorization and saves tokens to tokens.json (one-time setup).

Generate .gemini/settings.json from your .env file:

npm run setup:gemini

This script automatically:

• Reads your .env file
• Creates .gemini/settings.json with the correct paths and API keys
• Populates all environment variables from your .env file

Note: Run npm run setup:gemini again whenever you update your .env file or after building the project.

Once configured, start Gemini CLI and ask:

• "Play my Discover Weekly playlist"
• "Search for songs by The Beatles"
• "Pause Spotify"
• "Set a 30 minute sleep timer"
• "What's currently playing?"

• play_playlist - Play a playlist by name
• play_album - Play an album by name
• play_track - Play a track by name
• search_music - Search for music
• control_playback - Control playback (play, pause, skip, volume)
• get_current_playing - Get currently playing track
• set_sleep_timer - Set a sleep timer
• cancel_sleep_timer - Cancel active timers
• get_active_timers - List active timers

• Redirect URI mismatch: Ensure .env and Spotify Dashboard have the exact same URI (http://127.0.0.1:3000/callback)
• Invalid redirect URI: Must use 127.0.0.1 not localhost (Spotify requirement)
• Token expired: Delete tokens.json and run npm run auth again

• Verify absolute path to dist/server.js is correct
• Check environment variables are set (if using Method 2)
• Ensure Node.js is in PATH
• Test server manually: node dist/server.js (should start without errors)

• Make sure Spotify app is open and a device is active
• Verify tokens.json exists and is valid
• Check network connectivity

# Build TypeScript
npm run build

# Run MCP server (for testing)
npm start

# Authenticate with Spotify
npm run auth

# Development mode (auto-reload)
npm run dev

src/
  server.ts              # MCP server entry point
  auth-helper.ts         # Authentication helper script
  spotify/
    auth.ts             # OAuth authentication
    client.ts           # Spotify API client
  tools/                # MCP tool implementations
  timer.ts              # Timer manager