spotify

This MCP server implements a Kotlin-based Spotify integration that exposes a standardized set of MCP tools for controlling playback, managing playlists, and retrieving user information from the Spotify Web API. It supports playback actions (pause, resume, skip, seek, volume, repeat), playlist operations (get user playlists, get playlist items, create playlist, add/remove tracks), and user profile retrieval. The server is designed to be consumed via MCP clients (such as VS Code Copilot in Agent Mode or other MCP inspectors) and follows the MCP protocol for consistent tool invocation and input/output handling. To connect, run the server and point your MCP client to its endpoint; once connected, you can query tools, pass in structured inputs, and receive standardized responses from the Spotify integration.

Prerequisites:

• JDK 20 or higher
• Kotlin 2.1.10
• Gradle (wrapper included)
• Spotify Developer Account (for API access)

Installation steps:

1. Clone the repository: git clone https://github.com/yourusername/kotlin-mcp-server.git cd kotlin-mcp-server

2. Set up Spotify Developer credentials:

   • Create a Spotify App on the Spotify Developer Dashboard
   • Note your Client ID and Client Secret
   • Create a .env file in the project root with: SPOTIFY_CLIENT_ID="your-client-id" SPOTIFY_CLIENT_SECRET="your-client-secret"

3. Build the project (uses Gradle wrapper): ./gradlew installDist

4. Run the server executable: build/install/kotlin-mcp-server/bin/kotlin-mcp-server

5. Verify the server is running by accessing the MCP endpoint or using the provided SSE/STDIO modes as described in the README.

Environment variables and configuration:

• SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET must be provided for Spotify API access. Store them in a .env file as shown in the README.
• If you modify Main.kt to switch between Standard I/O and SSE modes, ensure you rebuild with the Gradle wrapper to reflect changes.
• When using MCP clients, you may need to adjust the server name (spotify-mcp-server) and the executable path in your client configuration to match your deployment.

Common issues:

• Invalid Spotify credentials or missing tokens: ensure the app is correctly configured on the Spotify developer dashboard and that your tokens are refreshed as needed.
• Network/firewall blocks to Spotify API endpoints: ensure outbound HTTPS requests are allowed from the server host.
• MCP client connection failures: confirm the server is running and that the client is pointed at the correct address and port (STDIO vs SSE endpoints).