diff --git a/README.md b/README.md index fbdfbae..b88f752 100644 --- a/README.md +++ b/README.md @@ -90,115 +90,51 @@ Instead of parsing large JSON responses, each tool returns exactly what you need --- -## Installation - -### 1. Prerequisites - -- Node.js 18+ installed -- A Spotify account (Premium recommended for full playback control) -- Spotify Developer App credentials - -### 2. Get Spotify API Credentials - -1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) -2. Create a new app -3. Note your **Client ID** and **Client Secret** -4. Add `http://localhost:8888/callback` to your app's Redirect URIs - -### 3. Install Dependencies - -```bash -npm install -``` - -### 4. Configure Environment - -Copy the example environment file and add your credentials: - -```bash -cp .env.example .env -``` - -Edit `.env` and add your credentials: - -```ini -SPOTIFY_CLIENT_ID=your_client_id_here -SPOTIFY_CLIENT_SECRET=your_client_secret_here -SPOTIFY_REDIRECT_URI=http://localhost:8888/callback -``` - -### 5. Authenticate with Spotify - -Run the authentication script (only needed once): - -```bash -npm run auth -``` - -This will: -- Open your browser -- Prompt you to log in to Spotify -- Save your tokens to `spotify-tokens.json` -- Automatically refresh tokens as needed +
-### 6. Build the Server +## Installation -```bash -npm run build -``` +
-### 7. Configure Your MCP Client - -#### For Claude Desktop - -Add to your `claude_desktop_config.json`: - -```json -{ - "mcpServers": { - "spotify": { - "command": "node", - "args": ["/ABSOLUTE/PATH/TO/spotify-mcp-server/dist/index.js"], - "env": { - "SPOTIFY_CLIENT_ID": "your_client_id", - "SPOTIFY_CLIENT_SECRET": "your_client_secret" - } - } - } -} -``` +
-#### For Other MCP Clients +| Step | Instructions | +|:---:|:---| +| **1. Prerequisites** | • Node.js 18+ installed
• Spotify Account (Premium recommended)
• Spotify Developer App credentials | +| **2. Get Credentials** | 1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
2. Create a new app
3. Note your **Client ID** and **Client Secret**
4. Add `http://localhost:8888/callback` to Redirect URIs | +| **3. Install** | `npm install` | +| **4. Configure** | Copy example env: `cp .env.example .env`

Edit `.env` with credentials:
`SPOTIFY_CLIENT_ID=your_id`
`SPOTIFY_CLIENT_SECRET=your_secret`
`SPOTIFY_REDIRECT_URI=http://localhost:8888/callback` | +| **5. Authenticate** | `npm run auth`
*(Opens browser to log in and saves tokens)* | +| **6. Build** | `npm run build` | +| **7. Configure Client** | Add to `claude_desktop_config.json`:
{
  "mcpServers": {
    "spotify": {
      "command": "node",
      "args": ["/PATH/TO/dist/index.js"],
      "env": { ... }
    }
  }
}
| -Use stdio transport with the command: -```bash -node /path/to/spotify-mcp-server/dist/index.js -``` +
--- +
+ ## Usage Once configured, restart your MCP client and you'll have access to all 51 tools! ### Example Queries -**For Dynamic HUDs:** -- "What's the current track name?" → Uses `spotify_get_track_name` -- "Get the artist" → Uses `spotify_get_artist_name` -- "What's the time remaining?" → Uses `spotify_get_time_remaining_formatted` -- "What's the playback progress percentage?" → Uses `spotify_get_track_progress_percentage` -- "Is music playing?" → Uses `spotify_is_playing` +| Category | User Query | Tool Used | +|:---:|:---|:---| +| **Dynamic HUDs** | "What's the current track name?" | `spotify_get_track_name` | +| | "Get the artist" | `spotify_get_artist_name` | +| | "What's the time remaining?" | `spotify_get_time_remaining_formatted` | +| | "What's the playback progress percentage?" | `spotify_get_track_progress_percentage` | +| | "Is music playing?" | `spotify_is_playing` | +| **Playback Control** | "Pause the music" | `spotify_pause` | +| | "Skip to the next song" | `spotify_next` | +| | "Set volume to 50%" | `spotify_set_volume` | +| | "Enable shuffle" | `spotify_set_shuffle` | +| **Discovery** | "Search for tracks by The Beatles" | `spotify_search` | +| | "Add this song to my library" | `spotify_save_track` | -**For Playback Control:** -- "Pause the music" → Uses `spotify_pause` -- "Skip to the next song" → Uses `spotify_next` -- "Set volume to 50%" → Uses `spotify_set_volume` -- "Enable shuffle" → Uses `spotify_set_shuffle` - -**For Discovery:** -- "Search for tracks by The Beatles" → Uses `spotify_search` -- "Add this song to my library" → Uses `spotify_save_track` +
--- @@ -208,8 +144,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools! +
+ ### Bulk State Tools (2) +
+
| Tool | Returns | Use Case | @@ -219,8 +159,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools!
+
+ ### Granular Track Info Tools (16) +
+
| Tool | Returns | Perfect For | @@ -244,8 +188,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools!
+
+ ### Granular Device Tools (6) +
+
| Tool | Returns | Perfect For | @@ -259,8 +207,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools!
+
+ ### Granular Playback State Tools (5) +
+
| Tool | Returns | Perfect For | @@ -273,8 +225,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools!
+
+ ### Playback Control Tools (7) +
+
| Tool | Parameters | Description | @@ -289,8 +245,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools!
+
+ ### Volume & Device Control Tools (2) +
+
| Tool | Parameters | Description | @@ -300,8 +260,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools!
+
+ ### Queue Management Tools (3) +
+
| Tool | Parameters | Description | @@ -312,8 +276,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools!
+
+ ### Search & Discovery Tools (5) +
+
| Tool | Parameters | Description | @@ -326,8 +294,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools!
+
+ ### Library Management Tools (5) +
+
| Tool | Parameters | Description | @@ -342,8 +314,12 @@ Once configured, restart your MCP client and you'll have access to all 51 tools! --- +
+ ## Architecture +
+ ``` spotify-mcp-server/ ├── src/ @@ -363,61 +339,67 @@ spotify-mcp-server/ --- +
+ ## Token Management -- Tokens are stored in `spotify-tokens.json` (automatically created) -- Access tokens are **automatically refreshed** when they expire -- You only need to run `npm run auth` once (or if tokens are revoked) -- Tokens persist across server restarts +| Token Details | +|:---| +| Tokens are stored in `spotify-tokens.json` (automatically created) | +| Access tokens are **automatically refreshed** when they expire | +| You only need to run `npm run auth` once (or if tokens are revoked) | +| Tokens persist across server restarts | + +
--- +
+ ## Error Handling The server provides clear, actionable error messages: -- **401 Unauthorized** → Re-run `npm run auth` -- **403 Forbidden** → Feature may require Spotify Premium -- **404 Not Found** → No active device or track -- **429 Rate Limit** → Too many requests, wait a moment - ---- +| Error Code | Meaning | +|:---:|:---| +| **401 Unauthorized** | Re-run `npm run auth` | +| **403 Forbidden** | Feature may require Spotify Premium | +| **404 Not Found** | No active device or track | +| **429 Rate Limit** | Too many requests, wait a moment | -## Development +
-### Run Tests +--- -```bash -npm test # Run all tests -npm run test:watch # Watch mode -npm run test:coverage # Coverage report -``` +
-### Run Linter +## Development -```bash -npm run lint -``` +| Task | Command | +|:---:|:---| +| **Run Tests** | `npm test` (all)
`npm run test:watch` (watch mode)
`npm run test:coverage` (report) | +| **Run Linter** | `npm run lint` | +| **Clean Build** | `npm run clean && npm run build` | +| **Debugging** | Server logs to stderr | -### Clean Build +
-```bash -npm run clean -npm run build -``` +--- -### Debugging +
-The server logs to stderr, so you can see diagnostic messages while the MCP protocol uses stdout. +## Use Cases ---- +
-## Use Cases +
### Dynamic HUD Applications Perfect for creating real-time music displays: +
+ ```javascript // Get individual values for your HUD components const trackName = await callTool("spotify_get_track_name"); @@ -428,20 +410,28 @@ const isPlaying = await callTool("spotify_is_playing"); const albumArt = await callTool("spotify_get_album_art_url"); ``` +
+ ### Music Visualizers Get precise timing and state info: +
+ ```javascript const progressMs = await callTool("spotify_get_track_progress_ms"); const durationMs = await callTool("spotify_get_track_duration_ms"); const isPlaying = await callTool("spotify_is_playing"); ``` +
+ ### AI Music Assistants Natural language control: +
+ ``` User: "What's playing?" AI: Uses spotify_get_track_name and spotify_get_artist_name @@ -455,46 +445,10 @@ AI: Uses spotify_next --- -## Contributing - -Contributions are welcome! This server follows the MCP specification and uses: - -- TypeScript with strict mode -- ESLint for code quality -- Zod for schema validation -- Axios for HTTP requests -- Vitest for testing - ---- +
## License MIT License - see LICENSE file for details ---- - -## Acknowledgments - -- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk) -- Uses the [Spotify Web API](https://developer.spotify.com/documentation/web-api) - ---- - -## Support - -For issues, please check: - -1. Your Spotify credentials are correct in `.env` -2. You've run `npm run auth` and authenticated successfully -3. You have an active Spotify device (desktop app, mobile, web player, etc.) -4. Your Spotify account has the necessary permissions (Premium for some features) - -For bugs or feature requests, please open an issue on GitHub. - ---- - -
- -**Built for the MCP community and dynamic HUD enthusiasts** -