TIDAL MCP — Complete, Safety-First TIDAL Server for AI Assistants

TIDAL MCP connects Codex, Claude Desktop, Claude Code, Cursor, and other stdio-compatible Model Context Protocol clients to a TIDAL account. Search the catalog, analyze playlists, discover music, read lyrics and credits, manage favorites, organize folders, and safely create or edit playlists through 112 typed MCP tools.

Positioning: as of September 4, 2026, this is the most complete public TIDAL MCP implementation found in a reproducible review of the current GitHub landscape. The claim is based on registered tool coverage, structured schemas, mutation safety, and automated test evidence—not marketing alone. See the dated comparison.

Why this TIDAL MCP exists

Most TIDAL integrations expose a small selection of search and playlist commands. TIDAL MCP is built as a complete local control surface for AI agents while keeping credentials and approvals on your machine.

• 112 discoverable tools: 74 reads, 36 mutation previews, and 2 approval-token commits.
• Broad account coverage: catalog, editorial pages, recommendations, lyrics, favorites, playlists, folders, mixes, images, and playback metadata.
• Safe writes: mutations are off by default and always require preview → explicit approval → commit.
• Private authentication: OAuth session data never travels through MCP tool responses.
• Typed and bounded: every input and output has a schema, limits, and MCP safety annotations.
• Verified quality: 100% statement and branch test coverage plus a real stdio handshake and an optional authenticated read-only smoke test.

What can an AI assistant do with TIDAL?

Ask naturally:

• “Analyze my entire workout playlist: artist concentration, eras, duplicates, duration, and sequencing.”
• “Find 20 tracks related to these three songs, exclude anything already in my playlist, and use at most two tracks per artist.”
• “Compare an artist’s albums, EPs, singles, appearances, top tracks, biography, and related artists.”
• “Show my favorite albums and playlists, then summarize how my collection is distributed.”
• “Prepare a new playlist from these recommendations and show me the exact changes before doing anything.”
• “Move these playlists into a folder, but ask for confirmation before changing my account.”

See real-world workflows and prompt examples.

Tool coverage

| Surface | Tools | Examples | | --- | ---: | --- | | Authentication, search, recommendations | 3 | status, multi-type search, deterministic multi-seed recommendations | | Catalog, editorial, discovery | 49 | tracks, albums, artists, videos, lyrics, credits, genres, Home, Explore, For You | | Collection, playlists, folders | 22 | favorites, counts, playlist items, owned/public playlists, folders, mixes | | Exact mutation previews | 36 | playlist CRUD, item moves, visibility, favorites, folders | | Approval-token commits | 2 | universal commit and compatible playlist-creation alias |

Every list operation is bounded and paginated. Every result uses a public-field allowlist so OAuth tokens, request clients, and internal session data cannot enter model context. The complete map is in API_COVERAGE.md.

Quick start

Requirements

• macOS or Linux; macOS is live-account tested
• Node.js 18 or newer
• Python 3.11–3.13
• uv
• A TIDAL account

1. Install and authenticate

npx -y @sickn33/tidal-mcp auth

Open the device-authorization URL, approve access in TIDAL, and return to the terminal. The session is stored in your private operating-system application-data directory, not in the repository.

Check or remove it at any time:

npx -y @sickn33/tidal-mcp auth --status
npx -y @sickn33/tidal-mcp auth --logout --yes

To install from source for development instead:

git clone https://github.com/sickn33/tidal-mcp.git
cd tidal-mcp
uv sync
uv run tidal-auth

2. Connect an MCP client

Use npm directly; the package launches the pinned Python implementation locally through uvx:

{
  "mcpServers": {
    "tidal": {
      "command": "npx",
      "args": [
        "-y",
        "@sickn33/tidal-mcp"
      ]
    }
  }
}

Restart or reconnect your MCP client, then ask: “Check my TIDAL authentication status.”

Enable safe account writes

Remote writes are disabled unless the MCP process receives:

"env": {
  "TIDAL_MCP_ENABLE_WRITES": "1"
}

Enabling the flag does not make mutations automatic. Every change still uses three explicit steps:

1. A named tidal_preview_* tool records the exact parameters and target metadata in a private, short-lived local draft.
2. The assistant presents that preview to the user.
3. Only after approval does tidal_commit_action accept the single-use token and execute exactly the recorded action.

Successful token replays return the stored result. Expired tokens fail closed. Ambiguous failed writes are locked to reduce duplicate effects. Destructive previews are clearly annotated.

Supported TIDAL operations

• Search and lookup: tracks, albums, artists, playlists, videos, mixes, users, barcodes, ISRCs.
• Track intelligence: details, radio, radio mixes, lyrics, credits, playback metadata, temporary account-scoped URLs.
• Artists and albums: discographies, EPs and singles, appearances, biographies, reviews, related artists, similar albums, resolutions, artwork, and editorial pages.
• Discovery: Home, Explore, For You, genres, moods, mixes, videos, hi-res, and local genre hubs.
• Collection: favorite tracks, albums, artists, playlists, videos, mixes, folders, and counts.
• Playlists: metadata, tracks, mixed items, counts, images, create/edit/delete/clear/merge, visibility, add/remove/reorder operations.
• Folders: inspect, create, rename, delete, and move collection-tree items.

The server intentionally does not download media, bypass DRM, expose raw OAuth methods, or provide an unrestricted private-endpoint proxy.

Configuration

| Variable | Default | Meaning | | --- | --- | --- | | TIDAL_MCP_ENABLE_WRITES | 0 | Permit approval-token commits for allowlisted account mutations | | TIDAL_MCP_DATA_DIR | OS application-data directory | Session and draft root | | TIDAL_MCP_SESSION_FILE | <data-dir>/session.json | Override the OAuth session path | | TIDAL_MCP_DRAFT_TTL_SECONDS | 900 | Approval lifetime, between 60 and 3600 seconds |

New private directories use mode 0700 and sensitive files use 0600 on systems supporting POSIX permissions. Existing custom parent directories are never silently permission-rewritten.

Verified quality

uv sync --all-groups
uv run ruff format --check .
uv run ruff check .
uv run pytest --cov=tidal_mcp --cov-report=term-missing
uv run python scripts/smoke_stdio.py
uv build

The coverage gate is 100% for statements and branches. Tests exercise every registered read and mutation route through the MCP schemas and the pinned tidalapi adapter without contacting TIDAL. The stdio smoke test launches the packaged protocol process and verifies all 112 tool schemas.

Official releases are published from GitHub Actions through npm Trusted Publishing, with no long-lived npm write token. npm attaches provenance automatically, and the same release workflow publishes the matching metadata to the official MCP Registry through GitHub OIDC.

An optional authenticated smoke test performs representative reads only:

uv run python scripts/smoke_live_read_only.py

Release maintainers can test the exact public npm package through the same MCP client path:

uv run python scripts/smoke_live_read_only.py \
  --command npx \
  --server-arg=-y \
  --server-arg=@sickn33/[email protected]

The deterministic evaluation suite and the dated competitive matrix make quality claims inspectable.

Architecture and compatibility

TIDAL provides developer APIs, but developer credentials are issued separately and the official surface does not cover every consumer-account workflow. This local server therefore pins tidalapi 0.8.11, an unofficial adapter around TIDAL’s consumer endpoints, for broad device-login coverage. TIDAL changes can require maintenance; the pinned dependency and live smoke test make that risk visible.

The server uses the MCP Python SDK over stdio. Blocking upstream calls run outside the async protocol event loop. It does not launch a Flask sidecar or store authentication in temporary directories.

Documentation

• Complete API coverage
• Use cases and prompt cookbook
• Frequently asked questions
• Security policy
• Competitive evidence
• Deterministic evaluation
• Contributing
• Changelog

Project status

Version 1.0.1 is the first fully automated supply-chain release. npm is the primary installation channel, and every release is also published to the official MCP Registry.

License, attribution, and trademark notice

MIT. This repository preserves the history and license of yuhuacheng/tidal-mcp; see NOTICE.md.

TIDAL is a trademark of its respective owner. This is an independent, unofficial community project and is not affiliated with, endorsed by, or sponsored by TIDAL. No TIDAL logo or album artwork is bundled with the project.