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

Installation

Requirements

• Python 3.10+
• uv (recommended) or pip

Setup

# 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

{
  "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

npx @modelcontextprotocol/inspector uv run tidal-mcp

Direct Usage

uv run tidal-mcp

Authentication

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

# 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)

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 and tidalapi.