Content
# Spotify MCP Tool
A powerful tool that combines Spotify API with Google's Gemini AI to provide music insights, recommendations, and analysis.
## Features
### Spotify Data Access
- User profile information
- Playlists and tracks
- Top tracks and artists
- Recently played tracks
- New releases
### AI-Powered Insights (Gemini)
- Comprehensive listening habit analysis
- Personalized track recommendations
- Playlist insights and analysis
- Question answering about playlists
- Music discovery suggestions
- Mood-based playlist generation
## Installation
1. Clone the repository:
```bash
git clone https://github.com/pradeepjung45/spotify_mcp.git
cd spotify_mcp
```
2. Create a virtual environment and install dependencies:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```
3. Set up environment variables:
Create a `.env` file in the root directory with the following:
```
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8000/callback
GEMINI_API_KEY=your_gemini_api_key
```
## Usage
### CLI Tool
The project includes a command-line interface for interacting with Spotify and Gemini AI:
1. Authenticate with Spotify:
```bash
python mcp_tools.py auth_url
```
This will provide a URL to open in your browser. After authorizing, you'll be redirected to a callback URL with a code parameter.
2. Complete authentication with the code:
```bash
python mcp_tools.py auth_url --code YOUR_CODE_HERE
```
3. Get your user profile:
```bash
python mcp_tools.py user_profile
```
4. Get your playlists:
```bash
python mcp_tools.py playlists
```
5. Get AI analysis of your listening habits:
```bash
python mcp_tools.py listening_analysis
```
6. Get AI-powered track recommendations:
```bash
python mcp_tools.py track_recommendations
```
7. Get insights about a specific playlist:
```bash
python mcp_tools.py playlist_insights --playlist-id YOUR_PLAYLIST_ID
```
8. Ask a question about a playlist:
```bash
python mcp_tools.py playlist_question --playlist-id YOUR_PLAYLIST_ID --question "What is the overall mood of this playlist?"
```
9. Get music discovery suggestions:
```bash
python mcp_tools.py music_discovery
```
10. Get a mood-based playlist suggestion:
```bash
python mcp_tools.py mood_playlist --mood happy
```
### FastAPI Server
The project also includes a FastAPI server for accessing the same functionality through a web interface:
1. Start the server:
```bash
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```
2. Open your browser and navigate to `http://localhost:8000`
3. Click "Login with Spotify" to authenticate
4. Access various endpoints for Spotify data and AI insights
## MCP Integration
This tool is designed to be used as an MCP (Model Context Protocol) tool with Claude Desktop. Once Claude Desktop is available, you can install the tool using:
```bash
mcp install mcp_tools.py
```
## Project Structure
- `app/` - FastAPI application
- `routers/` - API route handlers
- `services/` - Service classes for Spotify and Gemini
- `config.py` - Configuration settings
- `main.py` - FastAPI application entry point
- `mcp_tools.py` - MCP tool and CLI interface
## Requirements
- Python 3.8+
- Spotify Developer Account
- Google Gemini API Key
## License
MIT
## Acknowledgements
- [Spotify Web API](https://developer.spotify.com/documentation/web-api/)
- [Google Gemini AI](https://ai.google.dev/gemini-api)
- [FastAPI](https://fastapi.tiangolo.com/)
- [FastMCP](https://github.com/anthropics/fastmcp)