{"id":27161929,"url":"https://github.com/ejfox/vulpes-spotify-mcp","last_synced_at":"2025-04-09T00:58:26.783Z","repository":{"id":284966008,"uuid":"953245824","full_name":"ejfox/vulpes-spotify-mcp","owner":"ejfox","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-22T22:40:16.000Z","size":24,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T04:18:00.739Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ejfox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-22T22:40:13.000Z","updated_at":"2025-04-05T03:32:50.000Z","dependencies_parsed_at":"2025-03-28T17:08:29.872Z","dependency_job_id":"83fc0bc1-d4bd-4d0f-a580-1701df806af4","html_url":"https://github.com/ejfox/vulpes-spotify-mcp","commit_stats":null,"previous_names":["ejfox/vulpes-spotify-mcp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejfox%2Fvulpes-spotify-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejfox%2Fvulpes-spotify-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejfox%2Fvulpes-spotify-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ejfox%2Fvulpes-spotify-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ejfox","download_url":"https://codeload.github.com/ejfox/vulpes-spotify-mcp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247953104,"owners_count":21023947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-09T00:58:26.339Z","updated_at":"2025-04-09T00:58:26.773Z","avatar_url":"https://github.com/ejfox.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vuples Spotify MCP Server\n\nA Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Spotify, allowing them to search for and play tracks.\n\n## Features\n\n- Search for tracks by artist, title, or any query\n- Play tracks directly on your active Spotify device\n- Get information about your currently playing track\n- Find available Spotify playback devices\n- Combined search-and-play functionality\n- List user's Spotify playlists\n- View tracks within playlists\n- Play playlists (with optional shuffle mode)\n- Find and play playlists by name\n\n## Requirements\n\n- Node.js (v16+)\n- Spotify Developer Account\n- Spotify Premium account (for playback functionality)\n- An MCP-compatible client (e.g., Claude Desktop)\n\n## Installation\n\n1. Clone this repository:\n   ```bash\n   git clone https://github.com/yourusername/spotify-mcp.git\n   cd spotify-mcp\n   ```\n\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Create a `.env` file with your Spotify API credentials:\n   ```\n   SPOTIFY_CLIENT_ID=your_client_id\n   SPOTIFY_CLIENT_SECRET=your_client_secret\n   SPOTIFY_REDIRECT_URI=http://localhost:8888\n   \n   # Optional: For playback control\n   SPOTIFY_REFRESH_TOKEN=your_refresh_token\n   ```\n\n   You can get your Client ID and Secret from the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard/applications).\n\n4. Generate a refresh token (required for playback control):\n\n   There are two ways to get a refresh token:\n\n   **Option 1: Use the built-in script**\n   ```bash\n   npm run get-token\n   ```\n   This will start a local server and provide instructions in the terminal.\n   \n   **Option 2: Use the simple script (if option 1 doesn't work)**\n   ```bash\n   node src/simple-auth.js\n   ```\n   This will give you a URL to open in your browser. After authorizing, you'll be redirected to a URL. Copy that URL back to the terminal, and it will show you a curl command to get the refresh token.\n\n   Required scopes (already included in the scripts):\n   - `user-read-playback-state`\n   - `user-modify-playback-state`\n   - `user-read-currently-playing`\n   - `playlist-read-private`\n   - `playlist-read-collaborative`\n\n5. Add the refresh token to your `.env` file:\n   ```\n   SPOTIFY_REFRESH_TOKEN=your_refresh_token\n   ```\n\n6. Build the project:\n   ```bash\n   npm run build\n   ```\n\n## Usage with Claude Desktop\n\n1. First, ensure Spotify is open and playing on your device\n\n2. Add this server to your Claude Desktop configuration:\n\n   Edit your `claude_desktop_config.json` file (typically in `~/Library/Application Support/Claude/` on macOS or `%APPDATA%\\\\Claude\\\\` on Windows):\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"spotify\": {\n         \"command\": \"node\",\n         \"args\": [\"/absolute/path/to/vulpes-spotify-mcp/dist/index.js\"],\n         \"env\": {\n           \"SPOTIFY_CLIENT_ID\": \"your_client_id\",\n           \"SPOTIFY_CLIENT_SECRET\": \"your_client_secret\",\n           \"SPOTIFY_REDIRECT_URI\": \"http://localhost:8888\",\n           \"SPOTIFY_REFRESH_TOKEN\": \"your_refresh_token\"\n         }\n       }\n     }\n   }\n   ```\n\n   Make sure to replace `/absolute/path/to/vulpes-spotify-mcp` with the actual path to your project.\n\n3. Restart Claude Desktop\n\n4. You should now see the Spotify tools available when you click on the hammer icon in Claude Desktop\n\n## Available Tools\n\n- **spotify-search**: Search for tracks by query\n- **spotify-play**: Play a specific track by ID or URI\n- **spotify-currently-playing**: Get information about the currently playing track\n- **spotify-devices**: List available Spotify playback devices\n- **spotify-search-and-play**: Search for a track and automatically play the top result\n- **spotify-playlists**: Get a list of the user's Spotify playlists\n- **spotify-playlist-tracks**: Get tracks from a specific playlist\n- **spotify-play-playlist**: Play a specific playlist (with optional shuffle)\n- **spotify-find-playlist**: Find a playlist by name and play it (recommended for AI use)\n\n## Troubleshooting\n\n- **\"No active device found\"**: Make sure Spotify is open and playing on at least one of your devices\n- **\"Missing permissions\"**: Your refresh token may not have the required scopes\n- **\"Not premium\"**: Playback control requires a Spotify Premium account\n- **\"Issues with refresh token\"**: If your token expires, generate a new one using the steps in the installation section\n\n## Important Notes\n\n1. Always ensure Spotify is open on at least one device before using playback controls\n2. The refresh token in your `.env` file and Claude Desktop config must match\n3. After making changes to your configuration, restart Claude Desktop\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fejfox%2Fvulpes-spotify-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fejfox%2Fvulpes-spotify-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fejfox%2Fvulpes-spotify-mcp/lists"}