{
  "markdown": "# 🎵 TIDAL MCP (Community Maintained Fork)\n\n> **📢 Active Maintenance Notice**: This is an actively maintained community fork of [yuhuacheng/tidal-mcp](https://github.com/yuhuacheng/tidal-mcp).\n> The original repository appears unmaintained since May 2025. **Contributions, issues, and PRs are welcome here!**\n\n[![Active Development](https://img.shields.io/badge/status-actively%20maintained-brightgreen)](https://github.com/ibeal/tidal-mcp)\n[![Docker Support](https://img.shields.io/badge/docker-supported-blue)](https://github.com/ibeal/tidal-mcp#option-1-docker-recommended)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org/downloads/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)\n\n![Demo: Music Recommendations in Action](./assets/tidal_mcp_demo.gif)\n\nMost music platforms offer recommendations — Daily Discovery, Top Artists, New Arrivals, etc. — but even with the state-of-the-art system, they often feel too \"aggregated\". I wanted something more custom and context-aware.\n\nWith TIDAL MCP, you can ask for things like:\n\n> _\"Based on my last 10 favorites, find similar tracks — but only ones from recent years.\"_\n>\n> _\"Find me tracks like those in this playlist, but slower and more acoustic.\"_\n\nThe LLM filters and curates results using your input, finds similar tracks via TIDAL's API, and builds new playlists directly in your account.\n\n## 🆕 What's New in This Fork\n\nThis community fork includes significant improvements over the original:\n\n- ✅ **Docker Support**: Full Docker and docker-compose setup for easy deployment\n- ✅ **Search Functionality**: Search for tracks, albums, artists, and playlists across TIDAL\n- ✅ **Pagination**: Fetch all tracks from large playlists (no more 50-track limit!)\n- ✅ **Complete Playlist Editing**: Add, remove, reorder tracks, and update metadata\n- ✅ **Refactored Codebase**: ~60% smaller files with better organization and maintainability\n- ✅ **DRY Pagination Helper**: Reusable pagination utilities across all endpoints\n\n**See the full changelog and contribute at: https://github.com/ibeal/tidal-mcp**\n\n## Features\n\n- 🌟 **Music Recommendations**: Get personalized track recommendations based on your listening history **plus your custom criteria**\n- 🎵 **Full Playlist Management**: Create, view, edit, and delete playlists with complete control\n- 🔍 **Advanced Search**: Search across tracks, albums, artists, and playlists\n- 📄 **Smart Pagination**: Automatically fetch all tracks from playlists of any size\n- 🎛️ **Playlist Editing**: Add, remove, reorder tracks, and update metadata\n- 🐳 **Docker Ready**: Easy deployment with Docker and docker-compose support\n- 🔐 **OAuth Authentication**: Secure browser-based TIDAL login flow\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.10+ OR Docker\n- [uv](https://github.com/astral-sh/uv) (Python package manager) - only needed for non-Docker installation\n- TIDAL subscription\n\n### Installation\n\n#### Option 1: Docker (Recommended)\n\n1. Clone this repository:\n   ```bash\n   git clone https://github.com/ibeal/tidal-mcp.git\n   cd tidal-mcp\n   ```\n\n2. Build and run with Docker Compose:\n   ```bash\n   docker-compose up -d\n   ```\n\n   Or with Docker directly:\n   ```bash\n   docker build -t tidal-mcp .\n   docker run -d -p 5050:5050 --name tidal-mcp tidal-mcp\n   ```\n\n   The server will be available at `http://localhost:5050`.\n\n3. To customize the port, edit the `TIDAL_MCP_PORT` environment variable in `docker-compose.yml` or pass it to docker run:\n   ```bash\n   docker run -d -p 5100:5100 -e TIDAL_MCP_PORT=5100 --name tidal-mcp tidal-mcp\n   ```\n\n#### Option 2: Local Python Installation\n\n1. Clone this repository:\n\n   ```bash\n   git clone https://github.com/ibeal/tidal-mcp.git\n   cd tidal-mcp\n   ```\n\n2. Create a virtual environment and install dependencies using uv:\n\n   ```bash\n   uv venv\n   source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n   ```\n\n3. Install the package with all dependencies from the pyproject.toml file:\n\n   ```bash\n   uv pip install --editable .\n   ```\n\n   This will install all dependencies defined in the pyproject.toml file and set up the project in development mode.\n\n## MCP Client Configuration\n\n### Claude Desktop Configuration\n\nTo add this MCP server to Claude Desktop, you need to update the MCP configuration file.\n\n#### Option 1: Docker Configuration (if using Docker)\n\n```json\n{\n  \"mcpServers\": {\n    \"TIDAL Integration\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"--network\",\n        \"host\",\n        \"-v\",\n        \"/tmp:/tmp\",\n        \"tidal-mcp\"\n      ],\n      \"env\": {\n        \"TIDAL_MCP_PORT\": \"5050\"\n      }\n    }\n  }\n}\n```\n\n**Setup:**\n\n1. Build the Docker image:\n   ```bash\n   docker build -t tidal-mcp .\n   ```\n\n2. Authenticate with TIDAL (run this once):\n   ```bash\n   docker-compose -f docker-compose.auth.yml run --rm tidal-auth\n   ```\n\n   You'll see the OAuth URL in the output:\n   ```\n   ============================================================\n   TIDAL LOGIN REQUIRED\n   Please open this URL in your browser:\n\n   https://link.tidal.com/XXXXX\n\n   Expires in 300 seconds\n   ============================================================\n   ```\n\n   Open the URL in your browser, log in to TIDAL, and the session will be saved to `/tmp/tidal-session-oauth.json`.\n\n3. Update your Claude Desktop config (see above) and restart Claude Desktop.\n\n**Configuration details:**\n- `--network host` - Allows the container to use the host's network directly\n- `-v /tmp:/tmp` - Mounts the host's /tmp directory so the TIDAL session persists across container restarts\n\nTo use a custom port:\n```json\n{\n  \"mcpServers\": {\n    \"TIDAL Integration\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"--network\",\n        \"host\",\n        \"-v\",\n        \"/tmp:/tmp\",\n        \"-e\",\n        \"TIDAL_MCP_PORT=5100\",\n        \"tidal-mcp\"\n      ]\n    }\n  }\n}\n```\n\n#### Option 2: Local Python Configuration (if not using Docker)\n\n```json\n{\n  \"mcpServers\": {\n    \"TIDAL Integration\": {\n      \"command\": \"/path/to/your/uv\",\n      \"env\": {\n        \"TIDAL_MCP_PORT\": \"5100\"\n      },\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"requests\",\n        \"--with\",\n        \"mcp[cli]\",\n        \"--with\",\n        \"flask\",\n        \"--with\",\n        \"tidalapi\",\n        \"mcp\",\n        \"run\",\n        \"/path/to/your/project/tidal-mcp/mcp_server/server.py\"\n      ]\n    }\n  }\n}\n```\n\nExample scrrenshot of the MCP configuration in Claude Desktop:\n![Claude MCP Configuration](./assets/claude_desktop_config.png)\n\n### Cursor Configuration\n\nFor Cursor users, add this configuration to your MCP settings file (`~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"TIDAL Integration\": {\n      \"command\": \"/path/to/your/project/tidal-mcp/.venv/bin/python\",\n      \"env\": {\n        \"TIDAL_MCP_PORT\": \"5100\"\n      },\n      \"args\": [\"/path/to/your/project/tidal-mcp/start_mcp.py\"]\n    }\n  }\n}\n```\n\n**Important**: Replace `/path/to/your/project/tidal-mcp` with the actual path to your project directory.\n\n#### Steps to Install MCP Configuration in Cursor\n\n1. Create or edit the MCP configuration file at `~/.cursor/mcp.json`\n2. Add the TIDAL Integration configuration above\n3. Update the paths to match your actual project location\n4. Save the file\n5. Restart Cursor to load the new MCP server\n\n### Steps to Install MCP Configuration in Claude Desktop\n\n1. Open Claude Desktop\n2. Go to Settings > Developer\n3. Click on \"Edit Config\"\n4. Paste the modified JSON configuration\n5. Save the configuration\n6. Restart Claude Desktop\n\n## Suggested Prompt Starters\n\nOnce configured, you can interact with your TIDAL account through a LLM by asking questions like:\n\n- _“Recommend songs like those in this playlist, but slower and more acoustic.”_\n- _“Create a playlist based on my top tracks, but focused on chill, late-night vibes.”_\n- _“Find songs like these in playlist XYZ but in languages other than English.”_\n\n_💡 You can also ask the model to:_\n\n- Use more tracks as seeds to broaden the inspiration.\n- Return more recommendations if you want a longer playlist.\n- Or delete a playlist if you’re not into it — no pressure!\n\n## Available Tools\n\nThe TIDAL MCP integration provides the following tools:\n\n### Authentication & Core Features\n\n- `tidal_login`: Authenticate with TIDAL through browser login flow\n- `get_favorite_tracks`: Retrieve your favorite tracks from TIDAL\n- `recommend_tracks`: Get personalized music recommendations\n\n### Playlist Management\n\n- `create_tidal_playlist`: Create a new playlist in your TIDAL account\n- `get_user_playlists`: List all your playlists on TIDAL\n- `get_playlist_tracks`: Retrieve all tracks from a specific playlist (with automatic pagination)\n- `delete_tidal_playlist`: Delete a playlist from your TIDAL account\n- `add_tracks_to_playlist`: Add tracks to an existing playlist\n- `remove_tracks_from_playlist`: Remove tracks by ID or position index\n- `update_playlist_metadata`: Update playlist title and/or description\n- `reorder_playlist_tracks`: Move tracks to different positions within a playlist\n\n### Search & Discovery\n\n- `search_tidal`: Comprehensive search across all TIDAL content types\n- `search_tracks`: Search specifically for tracks/songs\n- `search_albums`: Search specifically for albums\n- `search_artists`: Search specifically for artists\n- `search_playlists`: Search specifically for playlists\n\n## License\n\n[MIT License](LICENSE)\n\n## Contributing\n\nThis is an actively maintained community fork. Contributions are welcome!\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Acknowledgements\n\n**Original Project:**\n- [yuhuacheng/tidal-mcp](https://github.com/yuhuacheng/tidal-mcp) - Original TIDAL MCP implementation\n\n**Contributors:**\n- [ra100](https://github.com/ra100) - Search functionality features\n\n**Libraries & Frameworks:**\n- [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/python-sdk)\n- [TIDAL Python API](https://github.com/tamland/python-tidal)\n",
  "bytes": 10241,
  "sha": "b0859d4cc36f61f92cae08c3d6af22d1a7adde228a3584d1e3654ac21c159ab8",
  "repo_slug": "ibeal/tidal-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ibeal_tidal_mcp_0d14a417/readme"
}