🎵 Multi-Agent Spotify Assistant using MCP

A beginner-friendly AI agent system that combines Spotify music control with intelligent web search to create your ultimate music companion! This project demonstrates advanced AI concepts like multi-agent systems, tool integration, and Model Context Protocol (MCP) using Google's Agent Development Kit (ADK).

🎯 What This Project Does

Imagine having a smart music friend who can:

• 🎶 Control your Spotify: Search songs, create playlists, manage playback
• 🔍 Research music topics: Find artist biographies, album stories, music history
• 🤖 Work as a team: Multiple AI agents collaborate to give you the best experience

Instead of one "do-everything" AI, this project uses three specialized agents that work together - just like a real team where each member has expertise in different areas!

🏗️ Architecture Overview

🧠 Understanding the Architecture

Think of this like a music store with specialists:

1. 🎵 MusicFriendManager (The Receptionist):

   • Talks to customers (you)
   • Decides which specialist can help
   • Coordinates everything

2. 🎧 SpotifySpecialist (The DJ):

   • Expert at all Spotify operations
   • Can search songs, make playlists, control playback
   • Uses Spotify's official tools

3. 📚 MusicInfoSpecialist (The Music Historian):

   • Expert at finding music information online
   • Researches artists, albums, music history
   • Uses Google Search to find detailed info

🔑 Key Concepts for ML Beginners

🤖 What are AI Agents?

Agents are AI programs that can:

• Think and make decisions
• Use tools (like searching the web or controlling apps)
• Communicate with other agents
• Complete tasks autonomously

🛠️ What are Tools?

Tools give agents superpowers! Examples:

• Spotify MCP Tool: Lets agents control Spotify
• Google Search Tool: Lets agents search the internet
• AgentTool: Lets one agent use another agent as a tool

🔌 What is MCP (Model Context Protocol)?

MCP is like a universal translator that lets AI agents talk to external services:

• It's a standard way for AI to connect to apps like Spotify
• Handles authentication and communication
• Makes it easy to add new capabilities to agents

🏢 What is a Multi-Agent System?

Instead of one giant AI trying to do everything:

• Divide and Conquer: Each agent specializes in specific tasks
• Collaboration: Agents work together and share information
• Scalability: Easy to add new specialists for new capabilities
• Maintainability: Easier to update or fix individual components

🚀 Getting Started

Prerequisites

Before we begin, make sure you have:

• Python 3.8+ installed
• Basic terminal/command prompt knowledge
• A Spotify account (free or premium)
• A Google AI API key (we'll get this together)

Step 1: Set Up the Spotify MCP Server

The Spotify MCP is a separate service that handles all Spotify operations.

1. Clone and set up the Spotify MCP:

# Navigate to your desktop or preferred directory
cd Desktop

# Clone the Spotify MCP repository
git clone https://github.com/varunneal/spotify-mcp.git


# Create a virtual environment (isolated Python environment)
python -m venv .venv

# Activate the virtual environment
# On Windows:
.venv\Scripts\activate
# On Mac/Linux:
source .venv/bin/activate

# Install the Spotify MCP
pip install -e .

2. Create a Spotify App (to get API credentials):

   • Go to Spotify Developer Dashboard
   • Click "Create App"
   • Fill in:
     • App Name: "My Music Agent"
     • App Description: "AI agent for music control"
     • Redirect URI: http://127.0.0.1:8080/callback
   • Save your Client ID and Client Secret

3. Configure the Spotify MCP:

# Create environment file for secrets
echo "SPOTIFY_CLIENT_ID=your_client_id_here" > .env
echo "SPOTIFY_CLIENT_SECRET=your_client_secret_here" >> .env

4. Test the Spotify MCP:

# This should start the server without errors
python -m uv run spotify-mcp

Step 2: Set Up the Main Agent System

1. Create your project directory:

cd Desktop
mkdir spotify-agent-demo
cd spotify-agent-demo

2. Create virtual environment for the main project:

python -m venv .venv
# Activate it
# Windows:
.venv\Scripts\activate
# Mac/Linux:
source .venv/bin/activate

3. Install Google ADK:

pip install google-adk

4. Get your Google AI API key:

   • Go to Google AI Studio
   • Create a new API key
   • Save it securely

5. Create the agent structure:

mkdir spotify-playlist-agent
cd spotify-playlist-agent

6. Create environment file:

echo "GOOGLE_GENAI_API_KEY=your_google_api_key_here" > .env

7. Copy the agent code:
   • Create agent.py with the code from this repository
   • Make sure to update the paths in the code to match your setup

Step 3: Understanding the Code Structure

Let's break down the main agent.py file:

🔌 MCP Connection Setup

spotify_tools = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command=r"path_to_your_spotify_mcp_python.exe",
            args=["-m", "uv", "run", "spotify-mcp"],
            working_dir=r"path_to_your_spotify_mcp_directory",
        )
    )
)

What this does: Connects our agent to the Spotify MCP server we set up earlier.

🎧 Spotify Specialist Agent

spotify_specialist = LlmAgent(
    name="SpotifySpecialist",
    model="gemini-2.5-flash-lite",
    instruction="You are a Spotify specialist...",
    tools=[spotify_tools]
)

What this does: Creates an AI agent that specializes in Spotify operations.

📚 Music Info Specialist Agent

music_info_specialist = LlmAgent(
    name="MusicInfoSpecialist",
    model="gemini-2.5-flash-lite",
    instruction="You are a music information specialist...",
    tools=[google_search]
)

What this does: Creates an AI agent that specializes in researching music information.

🎵 Manager Agent

music_friend_manager = LlmAgent(
    name="MusicFriendManager",
    model="gemini-2.5-flash",
    instruction="You are a friendly music assistant manager...",
    tools=[
        AgentTool(agent=spotify_specialist),
        AgentTool(agent=music_info_specialist)
    ]
)

What this does: Creates the main agent that coordinates between specialists.

Step 4: Running the System

1. Start the agent:

# Make sure you're in the spotify-agent-demo directory
# and your virtual environment is activated

adk web

2. Open your browser and go to http://localhost:8000

3. Start chatting with your music agent!

💬 Example Conversations

Spotify Operations

You: "Play some jazz music" Agent: Uses SpotifySpecialist to search for jazz and start playback

Music Research

You: "Tell me about Miles Davis" Agent: Uses MusicInfoSpecialist to search Google and provide detailed biography

Combined Operations

You: "Play Kind of Blue by Miles Davis and tell me about the album" Agent: Uses SpotifySpecialist to play the album, then MusicInfoSpecialist to research its history

🔧 Troubleshooting

Common Issues

1. "Connection closed" error:

   • Check that the Spotify MCP path is correct
   • Make sure the Spotify MCP virtual environment is set up properly

2. "Invalid redirect URI":

   • Add http://127.0.0.1:8080/callback to your Spotify app settings

3. "Google Search not working":

   • Verify your Google AI API key is correct
   • Check your internet connection

🆘 Getting Help

If you run into issues:

1. Check the error messages carefully
2. Verify all paths and API keys
3. Make sure both virtual environments are properly activated
4. Consult the ADK Documentation

🎓 Learning Outcomes

By building this project, you'll learn:

• Multi-agent system design
• Tool integration patterns
• MCP protocol usage
• API authentication and configuration
• Virtual environment management
• Modern AI agent development practices

🚀 Next Steps

Once you have this working, try:

1. Adding new specialists (e.g., a lyrics finder agent)
2. Customizing agent personalities
3. Adding more complex workflows
4. Integrating with other music services

📚 Additional Resources

• Google ADK Documentation
• Model Context Protocol
• Spotify Web API
• Google AI Studio

---