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

Go to Spotify Developer Dashboard
Create a new app
Copy your Client ID and Client Secret
Click "Edit Settings" → Add redirect URI: http://127.0.0.1:3000/callback
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