# 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

```bash
npm install
npm run build
```

### 2. Spotify Developer Setup

1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/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:

```env
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

```bash
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:

```bash
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

```bash
# 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
```