# TIDAL MCP Server
A traditional MCP (Model Context Protocol) server for TIDAL music streaming service. Clean API wrapper following official MCP best practices - thin wrappers around tidalapi methods with no custom business logic.
## Features
### 27 Tools
| Category | Tool | Description |
|----------|------|-------------|
| **Auth** | `login` | OAuth browser authentication |
| **Search** | `search_tracks` | Find tracks by name/artist |
| | `search_albums` | Find albums |
| | `search_artists` | Find artists |
| | `search_playlists` | Find public playlists |
| **Favorites** | `get_favorite_tracks` | Get liked tracks |
| | `get_favorite_albums` | Get saved albums |
| | `get_favorite_artists` | Get followed artists |
| | `add_track_to_favorites` | Like a track |
| | `remove_track_from_favorites` | Unlike a track |
| | `remove_album_from_favorites` | Remove saved album |
| **Playlists** | `get_user_playlists` | List your playlists |
| | `get_playlist_tracks` | Get tracks from playlist |
| | `create_playlist` | Create new playlist |
| | `add_tracks_to_playlist` | Add tracks to playlist |
| | `remove_tracks_from_playlist` | Remove tracks from playlist |
| | `update_playlist` | Update name/description |
| | `delete_playlist` | Delete a playlist |
| **Albums** | `get_album_tracks` | Get all album tracks |
| | `get_album` | Get album details |
| | `get_similar_albums` | Find similar albums |
| **Artists** | `get_artist` | Get artist details with bio |
| | `get_artist_albums` | Get artist discography |
| | `get_artist_top_tracks` | Get popular tracks |
| | `get_similar_artists` | Find similar artists |
| **Recommendations** | `get_track_radio` | Similar tracks to seed |
| | `get_artist_radio` | Tracks based on artist style |
## Installation
### Requirements
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (recommended) or pip
### Setup
```bash
# Clone and enter directory
cd tidal-mcp
# Install with uv
uv sync
# Or with pip
pip install -e .
```
## Usage
### With Claude Desktop
Add to your Claude Desktop config:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"tidal": {
"command": "/path/to/uv",
"args": [
"--directory", "/path/to/tidal-mcp",
"run", "tidal-mcp"
]
}
}
}
```
> **Note**: Use full path to `uv` (find with `which uv`)
### With MCP Inspector
```bash
npx @modelcontextprotocol/inspector uv run tidal-mcp
```
### Direct Usage
```bash
uv run tidal-mcp
```
## Authentication
```bash
python authenticate.py
```
## Example Workflows
### Create a Playlist from Search Results
1. `login` - Authenticate with TIDAL
2. `search_tracks("Radiohead Creep")` - Find tracks
3. `create_playlist("My Playlist", "A collection of favorites")` - Create playlist
4. `add_tracks_to_playlist(playlist_id, [track_ids...])` - Add tracks
### Browse and Add Album to Playlist
1. `search_albums("OK Computer")` - Find album
2. `get_album_tracks(album_id)` - Get all tracks
3. `add_tracks_to_playlist(playlist_id, [all_track_ids...])` - Add to playlist
### Manage Existing Playlist
1. `get_user_playlists()` - List your playlists
2. `get_playlist_tracks(playlist_id)` - View tracks
3. `remove_tracks_from_playlist(playlist_id, track_ids=[...])` - Remove tracks
4. `update_playlist(playlist_id, name="New Name")` - Rename
## Development
### Project Structure
```
tidal-mcp/
├── pyproject.toml # Project configuration
├── README.md # This file
├── CLAUDE.md # AI development guidance
└── src/
└── tidal_mcp/
├── __init__.py # Package init
├── models.py # Pydantic response models
└── server.py # MCP server with 27 tools
```
### Dependencies
- `fastmcp>=2.12.0` - MCP protocol framework
- `tidalapi>=0.8.6` - TIDAL API client (v0.8.6+ required for working OAuth)
- `anyio>=4.0.0` - Async utilities
### Testing
```bash
# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run tidal-mcp
# Quick protocol test
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}, "id": 1}' | uv run tidal-mcp
```
## Troubleshooting
### Authentication Fails
- Ensure tidalapi >= 0.8.6 (older versions have invalid OAuth credentials)
- Delete `.tidal-sessions/` and re-authenticate
### Search Returns No Results
- Simplify query (single artist or song name)
- Check spelling
### Port Conflicts (Inspector)
```bash
pkill -f "inspector|tidal-mcp"
```
## Future Roadmap
The server currently has 27 tools covering core TIDAL functionality. Potential future additions:
- **Remote Server**: HTTP/SSE transport for Claude.ai and mobile apps (see `docs/REMOTE-DEPLOYMENT.md`)
- **Advanced Search**: ISRC/UPC lookup for precise track/album identification
- **Playback**: Queue management and now-playing info (requires TIDAL Connect)
- **Social**: Following users, collaborative playlists
## License
MIT
## Credits
Built with [FastMCP](https://github.com/jlowin/fastmcp) and [tidalapi](https://github.com/tamland/python-tidal).