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)

Installation

From source

git clone https://github.com/teobouancheau/tidal-mcp.git
cd tidal-mcp
npm install
npm run build

Environment Setup

Create a .env file from the example:

cp .env.example .env

Set your credentials:

TIDAL_CLIENT_ID=your_client_id_here
TIDAL_CLIENT_SECRET=your_client_secret_here
TIDAL_DEFAULT_COUNTRY=US

Configuration

Local (stdio) -- Claude Desktop, Claude Code, Cursor

{
  "mcpServers": {
    "tidal": {
      "command": "node",
      "args": ["/path/to/tidal-mcp/dist/index.js"],
      "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

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

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Development

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 for details.

Acknowledgments

• TIDAL for the music streaming API
• Anthropic for the Model Context Protocol