Metadata-Version: 2.4
Name: yt-music-mcp
Version: 0.1.0
Summary: MCP server for YouTube Music — lets AI agents search, browse, and manage your library via ytmusicapi.
Project-URL: Homepage, https://github.com/Thanaen/yt-music-mcp
Project-URL: Repository, https://github.com/Thanaen/yt-music-mcp
Project-URL: Issues, https://github.com/Thanaen/yt-music-mcp/issues
Author: Thanaen
License: MIT
License-File: LICENSE
Keywords: ai-agents,claude,mcp,youtube-music,ytmusicapi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: ytmusicapi>=1.8.0
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# yt-music-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes [YouTube Music](https://music.youtube.com) to AI agents, via [`ytmusicapi`](https://github.com/sigma67/ytmusicapi).

Agents can search the catalog, browse artists/albums/songs, read the user's library and history, and create/edit/delete playlists, rate songs, and manage subscriptions.

---

## Quickstart

You need two things in your config:

1. **A way to run the server** — recommended: `uvx yt-music-mcp` (no install needed, [`uv`](https://docs.astral.sh/uv/) fetches it on first use).
2. **Your YouTube Music auth** — a one-time capture of request headers from `music.youtube.com`, stored either inline in the config or in a `browser.json` file.

### 1. Capture auth (one time, ~2-year validity)

Skip this if you only need public search/browsing.

1. Open <https://music.youtube.com> in a desktop browser, logged in.
2. Open DevTools (F12) → **Network** tab.
3. Click around to trigger traffic, then find any request to `/youtubei/v1/...`.
4. Right-click that request → **Copy** → **Copy request headers**.

Then run **one** of:

```bash
# Option A — print the JSON to stdout so you can paste it into your config.
uvx yt-music-mcp setup-auth --stdout

# Option B — write a browser.json file you'll reference by path.
uvx yt-music-mcp setup-auth --out ~/.yt-music-mcp/browser.json
```

Paste your headers when prompted, then Ctrl-D (Ctrl-Z + Enter on Windows).

### 2. Configure your MCP client

Pick your client and paste one of the snippets below. Use the **inline JSON** variant if you used `--stdout`, or the **file path** variant if you used `--out`.

#### Claude Desktop

Config file:

| OS | Path |
|---|---|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

**Inline JSON (recommended):**

```json
{
  "mcpServers": {
    "yt-music": {
      "command": "uvx",
      "args": ["yt-music-mcp"],
      "env": {
        "YTMUSIC_BROWSER_AUTH_JSON": "<paste the JSON from --stdout here>"
      }
    }
  }
}
```

**File path:**

```json
{
  "mcpServers": {
    "yt-music": {
      "command": "uvx",
      "args": ["yt-music-mcp"],
      "env": {
        "YTMUSIC_BROWSER_AUTH": "C:\\Users\\you\\.yt-music-mcp\\browser.json"
      }
    }
  }
}
```

> **Heads up:** Claude Desktop may not inherit your shell PATH. If `uvx` isn't found, use the absolute path (`which uvx` on macOS/Linux, `where uvx` on Windows).

Fully quit Claude Desktop (tray icon on Windows, ⌘-Q on macOS — closing the window isn't enough) and reopen. Click the 🔌 plug icon in any chat — you should see **yt-music** with 39 tools.

#### Claude Code

One command — pick the auth style that matches how you captured it:

```bash
# Inline JSON
claude mcp add yt-music -e YTMUSIC_BROWSER_AUTH_JSON="$(cat ~/.yt-music-mcp/browser.json)" -- uvx yt-music-mcp

# File path
claude mcp add yt-music -e YTMUSIC_BROWSER_AUTH=~/.yt-music-mcp/browser.json -- uvx yt-music-mcp
```

Scope the server to all projects or this one with `-s user` / `-s project`. Verify with `claude mcp list`, remove with `claude mcp remove yt-music`.

---

## Try it

Once connected, ask Claude things like:

- **Search & discovery**
  - *"Search YouTube Music for Radiohead albums."*
  - *"What are the global top 10 songs right now?"*
  - *"Find me some chill lo-fi playlists."*
- **Library (needs auth)**
  - *"Show my liked songs."*
  - *"What are the last 10 things I listened to?"*
  - *"Which artists am I subscribed to?"*
- **Playlist management (needs auth)**
  - *"Create a private playlist called 'Focus' and add these three songs: …"*
  - *"Add the top 5 tracks from the album OK Computer to my 'Road Trip' playlist."*
  - *"Remove the first track from my 'Focus' playlist."*
  - *"Like this song: <videoId>"*
- **Composite flows**
  - *"Find me 20 songs similar to 'Weird Fishes/Arpeggi' and put them in a new playlist called 'Radiohead-ish'."*
  - *"Make a playlist from my top artists this month."*

You'll see each tool call before it runs — review before approving anything that mutates your account.

---

## Alternative installation

If you don't want `uvx` for some reason, you can also install via [`pipx`](https://pipx.pypa.io):

```bash
pipx install yt-music-mcp
```

Then replace `"command": "uvx", "args": ["yt-music-mcp"]` with `"command": "yt-music-mcp"` in your config.

Or from source, for development:

```bash
git clone https://github.com/Thanaen/yt-music-mcp
cd yt-music-mcp
pip install -e ".[dev]"
pytest
```

---

## Configuration reference

All configuration is via environment variables. Resolved in this order:

| Variable | Purpose |
|---|---|
| `YTMUSIC_BROWSER_AUTH_JSON` | The full auth JSON as a string. Useful for keeping creds inline in a config file. |
| `YTMUSIC_BROWSER_AUTH` | Path to a `browser.json` file on disk. |
| *(neither)* | Unauthenticated mode — only public tools work. |

If both are set, `YTMUSIC_BROWSER_AUTH_JSON` wins.

---

## Tools reference

**39 tools total.** Unauthenticated tools work without any auth; authenticated ones need `YTMUSIC_BROWSER_AUTH_JSON` or `YTMUSIC_BROWSER_AUTH`.

### Unauthenticated
| Category | Tools |
|---|---|
| Search | `search`, `get_search_suggestions` |
| Browsing | `get_artist`, `get_artist_albums`, `get_album`, `get_album_browse_id`, `get_song`, `get_song_related`, `get_lyrics`, `get_watch_playlist`, `get_user`, `get_user_playlists`, `get_user_videos` |
| Explore | `get_home`, `get_charts`, `get_mood_categories`, `get_mood_playlists`, `get_explore` |
| Playlists (read) | `get_playlist` |

### Authenticated — reads
`get_library_playlists`, `get_library_songs`, `get_library_albums`, `get_library_artists`, `get_library_subscriptions`, `get_liked_songs`, `get_history`, `get_account_info`

### Authenticated — **mutations**
- **Playlists**: `create_playlist`, `edit_playlist`, `delete_playlist`, `add_playlist_items`, `remove_playlist_items`
- **Ratings**: `rate_song`, `rate_playlist`
- **Subscriptions**: `subscribe_artists`, `unsubscribe_artists`
- **History / library**: `add_history_item`, `remove_history_items`, `edit_song_library_status`

> ⚠️ **Mutations are always enabled.** Agents can delete your playlists. Review each proposed tool call in the Claude UI before approving. For a read-only setup, just don't provide auth — mutation tools will then fail with an auth error.

---

## Troubleshooting

**Claude Desktop shows "server failed to start"**
`uvx` (or `yt-music-mcp`) isn't on Claude Desktop's PATH. Replace `"command": "uvx"` with the absolute path — e.g. `C:\\Users\\you\\.local\\bin\\uvx.exe` on Windows, or the output of `which uvx` on macOS/Linux.

**"FileNotFoundError: YTMUSIC_BROWSER_AUTH does not point to a readable file"**
The env var's path is wrong. On Windows use `\\` or forward slashes in JSON. Verify with:
```bash
python -c "import os,pathlib; print(pathlib.Path(os.environ['YTMUSIC_BROWSER_AUTH']).is_file())"
```

**Library/playlist tools return "Please provide authentication"**
Your auth has expired or was captured from a logged-out session. Re-run `uvx yt-music-mcp setup-auth ...`.

**Nothing appears in Claude Desktop after editing the config**
Fully quit the app (tray icon / ⌘-Q — closing the window isn't enough), then reopen.

**Check what the server sees**
Run it manually with the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector uvx yt-music-mcp
```

---

## Not in v1

- **Uploads** (`upload_song`, `get_library_upload_*`, …) — may land later.
- **Podcasts** (`get_podcast`, `get_episode`, …) — may land later.

## License

MIT
