Skip to main content
Glama

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

Related MCP server: Spotify MCP Server (Python)

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

Available Tools

12 tools
cancel_sleep_timerC

Cancel an active sleep timer

Inputs: timerId.

control_playbackA

Control Spotify playback (play, pause, skip, volume). Note: skip-next and skip-previous will only skip once per call.

Inputs: action (required), value, deviceId.

get_active_timersB

Get list of active sleep timers

Inputs: no named parameters.

get_current_playingB

Get information about the currently playing track

Inputs: no named parameters.

get_devicesA

Get list of available Spotify devices and the current default device

Inputs: no named parameters.

play_albumC

Play a Spotify album by name and optional artist

Inputs: albumName (required), artistName, deviceId.

play_playlistC

Play a Spotify playlist by name

Inputs: playlistName (required), deviceId.

play_random_songC

Play a random song from Spotify

Inputs: deviceId.

play_trackC

Play a specific track by name and optional artist

Inputs: trackName (required), artistName, deviceId.

search_musicC

Search for music (tracks, albums, artists) on Spotify

Inputs: query (required), limit.

set_default_deviceB

Set the default Spotify device ID to use for all playback operations

Inputs: deviceId (required).

set_sleep_timerB

Set a sleep timer to automatically pause playback after specified minutes

Inputs: durationMinutes (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some potential overlap between playback control tools. The 'control_playback' tool handles play/pause/skip/volume, while 'play_track', 'play_album', 'play_playlist', and 'play_random_song' are all specific play initiation tools that could potentially be confused with the play function within 'control_playback'. However, the descriptions clarify their specific use cases well enough to avoid major confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case throughout. The naming is highly predictable and readable, with clear action-object pairs like 'get_current_playing', 'set_sleep_timer', 'play_album', and 'search_music'. There are no deviations from this consistent convention.

    Tool Count5/5

    With 12 tools, this server is well-scoped for Spotify control functionality. The count is appropriate for covering playback control, device management, search capabilities, and sleep timer features. Each tool appears to serve a distinct purpose that justifies its inclusion in the set.

    Completeness4/5

    The tool set provides excellent coverage of core Spotify functionality including playback control, device management, search, and sleep timers. The only minor gap is the lack of tools for playlist/library management (creating playlists, adding/removing tracks) and user profile operations, but the existing tools cover the most essential workflows for music playback and control.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Spotify through MCP, providing tools for searching tracks, artists, albums, playlists, and accessing user data like top tracks and recently played.
      -
    • F
      license
      A
      quality
      D
      maintenance
      Exposes Spotify controls as MCP tools for playback, playlist management, and AI playlist generation; includes a web app and supports multi-user profiles.
      14
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes Spotify search, playlist, library, discovery, and playback tools to AI assistants over MCP Streamable HTTP. Supports Spotify OAuth, multi-client MCP OAuth with PKCE and dynamic client registration, encrypted token storage, and self-hosted Docker deployment.
      1
      AGPL 3.0