mcp-deezer

Deezer MCP server for AI agents. 29 tools to search, manage playlists, favorites, and discover music. Works with a free Deezer account. No developer app needed.

Why this exists

Deezer closed their developer portal in 2025. No new OAuth apps. No API keys. This server uses your browser session cookie (ARL) instead. Free account, no registration, it just works.

For AI Agents — Installation Guide

If you are an AI agent reading this to install mcp-deezer for a user, follow these steps in order:

Step 1: Check prerequisites

• Python 3.12+ must be installed (python3 --version or python --version)
• If not installed, tell the user to install it from https://www.python.org/downloads/

Step 2: Install the package

pip install mcp-deezer

Or with uvx (no persistent install):

uvx mcp-deezer

Step 3: Get the user's Deezer ARL cookie

The user must do this manually in their browser:

1. Go to https://deezer.com and log in
2. Press F12 → Application → Cookies → deezer.com
3. Find the cookie named arl and copy its value (~192 character hex string)

The ARL looks like: a1b2c3d4e5f6... (192 hex chars)

Step 4: Configure the MCP server

Add this to the user's MCP client config. The DEEZER_ARL environment variable is required.

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "deezer": {
      "command": "uvx",
      "args": ["mcp-deezer"],
      "env": {
        "DEEZER_ARL": "PASTE_ARL_HERE"
      }
    }
  }
}

Claude Code — terminal:

claude mcp add deezer -e DEEZER_ARL=PASTE_ARL_HERE -- uvx mcp-deezer

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "deezer": {
      "command": "uvx",
      "args": ["mcp-deezer"],
      "env": {
        "DEEZER_ARL": "PASTE_ARL_HERE"
      }
    }
  }
}

Hermes Agent — ~/.hermes/config.yaml:

mcp_servers:
  deezer:
    command: uvx
    args: [mcp-deezer]
    env:
      DEEZER_ARL: "PASTE_ARL_HERE"

VS Code / Copilot — .vscode/mcp.json:

{
  "servers": {
    "deezer": {
      "command": "uvx",
      "args": ["mcp-deezer"],
      "env": {
        "DEEZER_ARL": "PASTE_ARL_HERE"
      }
    }
  }
}

Step 5: Restart the MCP client

Tell the user to restart their AI client (Claude Desktop, Cursor, etc.) for the server to load.

Step 6: Verify

Call get_me — it should return the user's Deezer profile ID. If it returns an error about DEEZER_ARL, the cookie is missing or expired.

Available Tools (29)

Tool	Description	Auth
get_me	User profile	✅
search	Search tracks, albums, artists, playlists	✅
get_track	Track details with lyrics	✅
get_artist	Artist details with bio	✅
get_album	Album details with tracklist	✅
get_playlist	Playlist details with tracks	✅
get_charts	Country charts (FR, US, DE...)	✅
get_similar_tracks	Similar tracks	✅
get_similar_artists	Similar artists	✅
get_flow	Personal Deezer Flow	✅
get_recommendations	Personalized recommendations	✅
get_recently_played	Listening history	✅
get_user_charts	Personal top tracks/artists	✅
get_favorite_tracks	Liked tracks	✅
get_favorite_albums	Liked albums	✅
get_favorite_artists	Followed artists	✅
get_favorite_playlists	Liked playlists	✅
add_track_to_favorite	Like a track	✅
remove_track_from_favorite	Unlike a track	✅
add_album_to_favorite	Like an album	✅
remove_album_from_favorite	Unlike an album	✅
add_artist_to_favorite	Follow an artist	✅
remove_artist_from_favorite	Unfollow an artist	✅
get_user_playlists	List user playlists	✅
create_playlist	Create a playlist	✅
update_playlist	Update playlist title/desc	✅
delete_playlist	Delete a playlist	✅
add_tracks_to_playlist	Add tracks to playlist	✅
remove_tracks_from_playlist	Remove tracks from playlist	✅

How It Works

AI Agent  ←── MCP (stdio) ──→  mcp-deezer  ←── GraphQL ──→  Deezer API
                                    │
                              ARL cookie (your session)

Uses deezer-python-gql — an unofficial client for Deezer's internal GraphQL API. Auth is via the ARL cookie stored in your browser.

FAQ (for agents)

Q: The user's ARL stopped working. A: Tell them to log out and back in to deezer.com, then grab the new arl cookie.

Q: Does this work with a free Deezer account? A: Yes. Unlike Spotify's API, Deezer works with free accounts.

Q: Is this against Deezer's ToS? A: It uses the same API as Deezer's web player. Your account, your data, your session cookie.

Q: Python 3.12+ is not available. A: Install it from https://www.python.org/downloads/ or use uvx which manages its own Python.

License

MIT