Spotify MCP Server for Gemini CLI

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

Features

• 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

Prerequisites

• Node.js 18+

• npm or yarn

• Spotify Developer account

• Google Gemini CLI installed (npm install -g @google/gemini-cli)

Quick Start

1. Install Dependencies

npm install
npm run build

2. Spotify Developer Setup

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.

3. Configure Environment

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

4. Authenticate

npm run auth

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

5. Configure Gemini CLI

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.

6. Use It!

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?"

Available MCP Tools

• 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

Troubleshooting

Authentication Issues

• 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

Gemini CLI Not Finding Server

• 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)

Server Errors

• Make sure Spotify app is open and a device is active

• Verify tokens.json exists and is valid

• Check network connectivity

Development

# 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

Project Structure

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