Spotify MCP Server

🚀 Kotlin MCP Server for Spotify

A Model Context Protocol (MCP) server implemented in Kotlin, integrated with the Spotify Web API. This server provides tools to control Spotify playback, manage playlists, and retrieve user information through a standardized interface.

🚀 Quick Start

This Kotlin MCP server integrated with Spotify Web API offers a range of functionalities for controlling Spotify playback, managing playlists, and retrieving user information. Follow the steps below to get started.

✨ Features

• Spotify Authentication: Manage Spotify API tokens and authentication.
• Playback Control: Pause/resume playback, skip to the next/previous track, adjust playback position, set volume, set repeat mode, and get the current queue.
• Playlist Management: Get user playlists, get playlist items, create playlists, and add/remove tracks from playlists.
• User Information: Retrieve user profiles.
• MCP Integration: Provide a standardized interface for interaction with external tools.

📦 Installation

Prerequisites

• JDK 1.8 or higher
• Kotlin 1.6.0 or higher
• Gradle 5.0 or higher
• A Spotify developer account (to obtain API credentials)

Clone the Repository

git clone [Repository URL]
cd mcp-spotify-server

Create a Configuration File

Create a config/application.properties file in the project root directory and add the following content:

# Spotify API configuration
spotify.client.id=[Your Client ID]
spotify.client.secret=[Your Client Secret]
spotify.redirect.uri=[Redirect URI]

# MCP server configuration
server.port=8080

Obtain Spotify Developer Credentials

Log in to the Spotify Developer Dashboard and create a new application to obtain the CLIENT_ID and CLIENT_SECRET.

💻 Usage Examples

Standard I/O Mode

# Run the server
./gradlew run

# Generate an executable file
./gradlew build

To connect to the MCP server via VS Code, configure it as follows:

1. Open VS Code settings (File -> Settings).
2. Click Terminal and select Run on startup.
3. Add cd [Project Path] && ./gradlew run to the startup command.

SSE Mode

# Start the server
./gradlew run --args="--sse"

# Stop the server
curl -X POST http://localhost:8080/stop

📚 Documentation

Project Structure

src/main/kotlin/
├── mcpserver/spotify/
│   ├── services/          # Spotify API call services
│   └── tools/            # MCP tool implementations
└── mcpserver/spotifymcp/
    └── tools/            # Third - party tool interfaces

Available Tools

Playback Control

• Pause playback
• Resume playback
• Skip to the next track
• Skip to the previous track
• Adjust playback position
• Set volume
• Set repeat mode
• Get the current queue

Playlist Management

• Get user playlists
• Get playlist items
• Create a playlist
• Add tracks to a playlist
• Remove tracks from a playlist

User Information

• Retrieve the current user's profile information

Development Guide

Error Handling

The project uses a custom sealed class SpotifyResult<T, E> for error handling:

• SpotifyResult.Success<T>: Contains successful response data.
• SpotifyResult.Failure<E>: Contains exceptions and error details. Use the safeSpotifyApiCall function to make API calls:

val result = safeSpotifyApiCall<ResponseType, ErrorType> {
    // Specific API call code
}

Adding New Tools

To add a new tool to the MCP server, follow these steps:

1. Create a new Kotlin file in the mcpserver/spotifymcp/tools package.
2. Define a function that accepts a Server instance and necessary services as parameters.
3. Register the tool using server.addTool(), specifying the name, description, and input schema.
4. Implement the specific functionality of the tool in the callback.

Testing Guide

Running Tests

# Run all tests
./gradlew test

# Run a specific test class
./gradlew test --tests "mcpserver.spotify.services.playerservice.SpotifyPlayerServiceImplTest"

# Run a specific test method
./gradlew test --tests "mcpserver.spotify.services.playerservice.SpotifyPlayerServiceImplTest.playTrack should return success when API call succeeds"

Writing Tests

The project uses JUnit 5 for testing. Test code should be placed in the src/test/kotlin directory, following the same structure as the main code. For tests that require simulating HTTP requests, it is recommended to use Ktor's MockEngine to simulate different response scenarios and test both successful and failed API calls.

🤝 Project Contribution

Contributions are welcome! Please fork this repository and carefully read the Contribution Guidelines before submitting your changes.