Content
# TIDAL MCP
[](https://www.npmjs.com/package/tidal-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://github.com/teobouancheau/tidal-mcp)
A Model Context Protocol (MCP) server that gives AI assistants full access to the TIDAL music streaming API. Search, browse, manage playlists, curate collections, and discover music. Works with Claude Desktop, Claude Code, Claude.ai, Cursor and any MCP-compatible client.
Supports both **local** (stdio) and **remote** (Streamable HTTP) transports.
## Features
- **Search** tracks, albums, artists, playlists, and videos
- **Browse** genres, similar content, artist radio, and recommendations
- **Get details** for tracks, albums, artists, videos, and playlists
- **Lyrics & credits** for any track
- **Playlist CRUD** create, update, delete, add/remove items
- **Collection management** add/remove favorites (tracks, albums, artists, playlists, videos)
- **Social** follow/unfollow artists
- **Discovery** similar tracks, albums, artists, videos, personalized mixes
- **History** view and manage search history
## Prerequisites
- Node.js 20+
- TIDAL Developer account with OAuth client credentials ([developer.tidal.com](https://developer.tidal.com))
## Installation
### Via npm (Recommended)
```bash
npm install -g tidal-mcp
```
### Via npx (no installation)
Configure directly with npx (see Configuration section).
### From source
```bash
git clone https://github.com/teobouancheau/tidal-mcp.git
cd tidal-mcp
npm install
npm run build
```
## Configuration
### Local (stdio) -- Claude Desktop, Claude Code, Cursor
#### Quick Start with npx
```json
{
"mcpServers": {
"tidal": {
"command": "npx",
"args": ["-y", "tidal-mcp"],
"env": {
"TIDAL_CLIENT_ID": "your_client_id",
"TIDAL_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
#### With Global Installation
```bash
npm install -g tidal-mcp
```
```json
{
"mcpServers": {
"tidal": {
"command": "tidal-mcp",
"env": {
"TIDAL_CLIENT_ID": "your_client_id",
"TIDAL_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
#### Configuration File Locations
| Client | Path |
| ---------------------------- | ----------------------------------------------------------------- |
| **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Claude Desktop (Linux)** | `~/.config/Claude/claude_desktop_config.json` |
| **Claude Code** | `.mcp.json` in your project or `~/.claude/settings.json` |
| **Cursor** | `.cursor/mcp.json` in your project |
Restart your client after updating configuration.
### Remote (HTTP) -- Claude.ai, Claude Mobile, Custom Connectors
```bash
npm run build
npm run start:http
```
The server listens on `PORT` (default 3000). Set `PORT` environment variable to change.
#### Connect via Claude.ai
1. Go to **Settings > Connectors**
2. Click **Add custom connector**
3. Enter your server URL (e.g., `https://your-app.example.com/mcp`)
4. Click **Add**
## MCP Tools
### Search & Discovery (4 tools)
#### search
Search TIDAL for tracks, albums, artists, playlists, and videos.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string | required | Search query |
| `countryCode` | string | "US" | ISO 3166-1 alpha-2 country code |
| `type` | string | "all" | Filter: all, tracks, albums, artists, playlists, videos |
| `limit` | number | 10 | Results per page (1-50) |
| `cursor` | string | - | Pagination cursor |
| `explicitFilter` | string | "INCLUDE" | INCLUDE or EXCLUDE explicit content |
#### search_suggestions
Get autocomplete suggestions for a partial search query.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string | required | Partial search query |
| `countryCode` | string | "US" | Country code |
#### get_genres
Browse all available music genres on TIDAL.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `countryCode` | string | "US" | Country code |
#### get_search_history
View recent search history.
### Tracks (4 tools)
#### get_track
Get detailed metadata for a TIDAL track.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL track ID |
| `countryCode` | string | "US" | Country code |
**Returns:** title, artists, album, duration, ISRC, BPM, popularity, explicit status
#### get_lyrics
Get song lyrics for a track.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `trackId` | string | required | TIDAL track ID |
| `countryCode` | string | "US" | Country code |
#### get_credits
Get production credits for a track.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `trackId` | string | required | TIDAL track ID |
| `countryCode` | string | "US" | Country code |
**Returns:** producers, writers, performers, engineers
#### get_similar_tracks
Find tracks similar to a given track.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `trackId` | string | required | TIDAL track ID |
| `countryCode` | string | "US" | Country code |
| `cursor` | string | - | Pagination cursor |
### Albums (2 tools)
#### get_album
Get album details including track listing.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL album ID |
| `countryCode` | string | "US" | Country code |
| `cursor` | string | - | Pagination cursor for tracks |
**Returns:** title, artists, type (album/EP/single), release date, track listing, duration
#### get_similar_albums
Find albums similar to a given album.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `albumId` | string | required | TIDAL album ID |
| `countryCode` | string | "US" | Country code |
| `cursor` | string | - | Pagination cursor |
### Artists (7 tools)
#### get_artist
Get artist details with biography.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL artist ID |
| `countryCode` | string | "US" | Country code |
#### get_artist_albums
Get an artist's discography.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL artist ID |
| `countryCode` | string | "US" | Country code |
| `cursor` | string | - | Pagination cursor |
#### get_artist_tracks
Get an artist's top/popular tracks.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL artist ID |
| `countryCode` | string | "US" | Country code |
| `cursor` | string | - | Pagination cursor |
#### get_artist_videos
Get an artist's music videos.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL artist ID |
| `countryCode` | string | "US" | Country code |
| `cursor` | string | - | Pagination cursor |
#### get_artist_radio
Get a radio station of tracks based on an artist.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL artist ID |
| `countryCode` | string | "US" | Country code |
| `cursor` | string | - | Pagination cursor |
#### get_similar_artists
Find artists similar to a given artist.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL artist ID |
| `countryCode` | string | "US" | Country code |
#### follow_artist / unfollow_artist
Follow or unfollow an artist on TIDAL.
| Parameter | Type | Description |
| --- | --- | --- |
| `artistId` | string | TIDAL artist ID |
### Videos (2 tools)
#### get_video
Get video details from TIDAL.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL video ID |
| `countryCode` | string | "US" | Country code |
#### get_similar_videos
Find videos similar to a given video.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `videoId` | string | required | TIDAL video ID |
| `countryCode` | string | "US" | Country code |
| `cursor` | string | - | Pagination cursor |
### Playlists (6 tools)
#### get_playlist
Get playlist details with items listing.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | string | required | TIDAL playlist UUID |
| `countryCode` | string | "US" | Country code |
| `cursor` | string | - | Pagination cursor for items |
#### create_playlist
Create a new playlist.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | string | required | Playlist name |
| `description` | string | - | Playlist description |
| `accessType` | string | "PUBLIC" | PUBLIC or UNLISTED |
#### update_playlist
Update an existing playlist.
| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | Playlist UUID (required) |
| `name` | string | New name |
| `description` | string | New description |
| `accessType` | string | PUBLIC or UNLISTED |
#### delete_playlist
Permanently delete a playlist.
| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | Playlist UUID |
#### add_playlist_items
Add tracks or videos to a playlist (max 20 per request).
| Parameter | Type | Description |
| --- | --- | --- |
| `playlistId` | string | Playlist UUID |
| `items` | array | Items to add: `[{id, type: "tracks"\|"videos"}]` |
| `positionBefore` | string | Insert before this position (optional) |
#### remove_playlist_items
Remove tracks or videos from a playlist (max 20 per request).
| Parameter | Type | Description |
| --- | --- | --- |
| `playlistId` | string | Playlist UUID |
| `items` | array | Items to remove: `[{id, type, itemId}]` |
### User & Collections (5 tools)
#### get_user
Get user profile. Omit ID for current authenticated user.
| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | User ID (optional) |
#### get_collection
Browse a user's saved collection (favorites).
| Parameter | Type | Description |
| --- | --- | --- |
| `collectionId` | string | User collection UUID |
| `type` | string | tracks, albums, artists, playlists, or videos |
| `cursor` | string | Pagination cursor |
#### add_to_collection
Add items to a user collection (max 20 per request).
| Parameter | Type | Description |
| --- | --- | --- |
| `collectionId` | string | Collection UUID |
| `type` | string | tracks, albums, artists, playlists, or videos |
| `ids` | string[] | Resource IDs to add |
#### remove_from_collection
Remove items from a user collection (max 20 per request).
| Parameter | Type | Description |
| --- | --- | --- |
| `collectionId` | string | Collection UUID |
| `type` | string | tracks, albums, artists, playlists, or videos |
| `ids` | string[] | Resource IDs to remove |
#### get_recommendations
Get personalized music recommendations.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `userId` | string | required | TIDAL user ID |
| `type` | string | "discoveryMixes" | discoveryMixes, myMixes, or newArrivalMixes |
### Mixes & History (3 tools)
#### get_mixes
Get personalized TIDAL mixes.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `mixType` | string | required | daily, discovery, or new-releases |
| `countryCode` | string | "US" | Country code |
#### delete_search_history_entry
Delete a specific entry from search history.
| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | Search history entry ID |
## Usage Examples
### Search and discover
```
"Search TIDAL for 'Daft Punk' and get details on their top tracks"
```
### Explore an artist
```
"Who are artists similar to Radiohead? Show me their discography"
```
### Get lyrics and credits
```
"Get the lyrics and production credits for 'Bohemian Rhapsody'"
```
### Build a playlist
```
"Create a playlist called 'Morning Jazz' and add these track IDs to it"
```
### Music discovery
```
"Find tracks similar to this song and create a radio station from this artist"
```
### Manage collection
```
"Add these albums to my favorites collection"
```
## Testing
```bash
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
```
## Development
```bash
npm run dev # Watch mode
npm run build # Build for production
npm run rebuild # Clean and rebuild
npm start # Run server (stdio)
npm run start:http # Run server (HTTP)
npm run validate # Typecheck + lint + test
```
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Run tests (`npm run validate`)
4. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) for details.
## Acknowledgments
- [TIDAL](https://tidal.com) for the music streaming API
- [Anthropic](https://anthropic.com) for the Model Context Protocol
---
<div align="center">
<strong>Built by <a href="https://github.com/teobouancheau">teobouancheau</a></strong>
</div>
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available