# yt-music-mcp

Simple YouTube Music MCP server that uses STDIO transport, compatible with Claude Code `~/.claude.json` MCP config.

## Features

- `search_songs`
- `search_artists`
- `get_playlists`
- `create_playlist`
- `add_to_playlist`
- `remove_from_playlist`
- `get_playlist_items`
- `auth_callback`

## Requirements

- Node.js 18+
- Google OAuth client with YouTube Data API v3 enabled
- Environment variables:
  - `GOOGLE_CLIENT_ID`
  - `GOOGLE_CLIENT_SECRET`

## Install

```bash
npm install
npm run build
```

## Claude Code config

Add this to `~/.claude.json`:

```json
{
  "mcpServers": {
    "yt-music": {
      "command": "node",
      "args": [
        "/Users/fperalta/Documents/projects/openclaw/yt-music-mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

## Authentication flow

On first run, the server writes a Google auth URL to `stderr`.

1. Open the URL in your browser.
2. Approve access.
3. Copy the authorization code.
4. Call the MCP tool `auth_callback` with that code.
5. The refresh token is saved to `~/.yt-music-mcp/tokens.json`.

After that, future runs reuse the saved refresh token automatically.

## Notes

- Transport is STDIO only, no HTTP server.
- Uses YouTube Data API v3 via `googleapis`.
- Song search filters to YouTube's Music category (`videoCategoryId=10`).
- `remove_from_playlist` removes by `playlistId + videoIds`, so if the same video appears multiple times, all matching entries are removed.

## Development

```bash
npm run build
node dist/index.js
```

The process should stay alive and wait for MCP messages on stdin.