youtube-music-mcp

youtube-music-mcp is a small local Model Context Protocol server for searching YouTube Music and working with playlists. It exposes seven focused tools over STDIO and uses ytmusicapi for every interaction with YouTube Music. Playlist creation, additions, and specific track removals require explicit confirmation. It does not expose playlist deletion, bulk library removal, likes, history, uploads, subscriptions, or account-management operations.

Architecture

• server.py configures MCP, registers tools, disables SDK telemetry, and starts STDIO.

• config.py resolves and validates the authentication-file path without reading its contents.

• client.py owns the single, lazy YTMusic instance used by every tool.

• schemas.py defines the allowlisted structured outputs.

• tools/search.py contains identity and song-search behavior.

• tools/playlists.py contains playlist reads and confirmation-gated writes.

The server does not expose an HTTP transport. It does not send telemetry or analytics, and the application never calls an HTTP library directly.

Related MCP server: yt-curator-mcp

Requirements

• Python 3.12 or newer

• uv

• A YouTube Music browser-auth file for live operations

Installation

Clone the repository and install the locked environment:

git clone https://github.com/ElisonSz/youtube-music-mcp.git
cd youtube-music-mcp
uv sync --locked --dev

Run the MCP server directly with:

uv run youtube-music-mcp

The process waits for MCP messages on STDIN and writes protocol messages to STDOUT.

Authentication

The default authentication path is:

~/.config/youtube-music-mcp/browser.json

Follow the ytmusicapi browser-authentication instructions to locate a successful authenticated POST /browse request on music.youtube.com. Firefox's Copy Request Headers option provides the most reliable input format. In Chrome or Edge, copy the contents of the Request Headers section; Copy as fetch can omit the cookie. Then run the project's interactive setup CLI:

uv run ytmusic-mcp setup-auth

The command creates the configuration directory, asks for the request headers with terminal echo disabled, writes the file with mode 0600, and validates it with a minimal account-information request. Finish multiline input by typing END on a separate line and pressing Enter. The command also accepts EOF. It displays only the validated account name and channel handle. setup-auth is a local administration command and is not exposed as an MCP tool.

The pasted data must include Authorization, Cookie, and X-Goog-AuthUser. The CLI reports missing or invalid header names, but never their values. If YouTube rejects the session, capture fresh headers after confirming that the selected /browse request completed successfully while you were signed in.

If the browser copies header names and values in a format that cannot be parsed, use guided mode:

uv run ytmusic-mcp setup-auth --manual

Copy only the value of each requested header from DevTools. All three inputs are hidden. The CLI does not repeat or log their values.

To use another location, set YTMUSIC_AUTH_FILE in the environment that starts the MCP server:

export YTMUSIC_AUTH_FILE=/absolute/path/to/browser.json
uv run ytmusic-mcp setup-auth

On POSIX systems the file must be owned by the current user and must not grant permissions to its group or other users. The server accepts 0600, 0400, or stricter modes. It never prints the file contents, cookies, or authorization headers.

The server initializes YTMusic only when a tool needs to contact YouTube Music. Creation and addition previews are local; removal previews authenticate and read the current playlist so they can resolve exact items, but do not modify it. The normal MCP server never creates or prompts for credentials. If authentication is missing, it refuses to start and reports:

Authentication not configured. Run: ytmusic-mcp setup-auth

If credentials that previously worked start failing later, the YouTube Music browser session may have expired or been revoked. Sign in to YouTube Music again, capture fresh request headers, and rerun ytmusic-mcp setup-auth to replace browser.json after reviewing the overwrite prompt.

Run the local, read-only diagnostic at any time with:

uv run ytmusic-mcp doctor

It validates the authentication-file metadata and makes one minimal account-information request. It reports only whether configuration and authentication are valid, followed by the allowlisted account name and channel handle. It never prints the authentication path, headers, cookies, or raw responses, and it does not modify the account.

Codex integration

If the package is installed as a uv tool, register its STDIO server with:

uv tool install .
codex mcp add ytmusic -- ytmusic-mcp serve

During development, run it directly from the project without installing a global tool:

codex mcp add ytmusic -- uv run --project /path/to/youtube-music-mcp ytmusic-mcp serve

The equivalent project-scoped .codex/config.toml entry is:

[mcp_servers.ytmusic]
command = "uv"
args = ["run", "--project", "/path/to/youtube-music-mcp", "ytmusic-mcp", "serve"]
env_vars = ["YTMUSIC_AUTH_FILE"]
default_tools_approval_mode = "writes"
startup_timeout_sec = 20

You may omit env_vars when using the default authentication path. Restart Codex after changing the configuration, then use /mcp to inspect the connected server. See the official Codex MCP documentation for the current CLI, IDE, and config.toml options.

MCP tools

Search results contain only videoId, title, artists, album, duration, and isExplicit. Playlist and track results are similarly reduced to the documented fields; each playlist track includes videoId, setVideoId, title, artists, duration, and its one-based position. Raw ytmusicapi responses are never returned.

Confirming writes

create_playlist, add_tracks, and remove_tracks default to confirm=false. In that mode they return a preview without modifying YouTube Music. Removal previews read the current playlist so they can resolve exact playlist-item IDs.

Set confirm=true only after reviewing that preview. Confirmed calls are not idempotent: repeating one may create another playlist or add tracks again. add_tracks passes allow_duplicates to ytmusicapi and defaults it to false.

Conceptual write workflow:

create_playlist(title="Road trip", privacy="PRIVATE", confirm=False)
add_tracks(playlist_id="...", video_ids=["..."], confirm=False)
remove_tracks(playlist_id="...", items=[{"set_video_id": "..."}], confirm=False)

Review the returned preview before repeating the intended call with confirm=True.

Removing playlist tracks

remove_tracks is destructive. A videoId identifies a song, while setVideoId identifies one specific occurrence of that song inside a playlist. The tool always reads the playlist and obtains the videoId/setVideoId pair from YouTube Music instead of trusting a caller-supplied pairing.

If a video_id occurs once, the preview resolves its setVideoId. If it occurs more than once, the tool makes no change and returns every occurrence with its setVideoId, title, artists, and position. Select the intended occurrence explicitly before confirming:

remove_tracks(
    playlist_id="...",
    items=[{"video_id": "..."}],
    confirm=False,
)

After reviewing the preview:

remove_tracks(
    playlist_id="...",
    items=[{"set_video_id": "..."}],
    confirm=True,
)

A confirmed call reads the playlist again, aborts if a selected setVideoId no longer exists, deduplicates repeated selections, calls ytmusicapi.remove_playlist_items, and reads the playlist once more to verify that every selected occurrence disappeared.

Development

Run the same checks used by CI:

uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build --no-sources

Tests inject a mocked YTMusic backend and never use a real account or authentication file. CI also installs the built wheel in an isolated environment and runs ytmusic-mcp --help as a package smoke test.

The project follows Semantic Versioning and remains in 0.x.x while its public API is unstable. Commit messages follow Conventional Commits using feat:, fix:, refactor:, test:, docs:, chore:, and security:.

Limitations

• Authenticated operations depend on browser-session credentials and unofficial APIs.

• Browser authentication can expire or be invalidated by signing out.

• get_playlist returns at most 100 tracks per call in version 0.1.0, while trackCount describes the full playlist.

• Permission-bit enforcement is available on POSIX systems; Windows ACLs are outside the scope of version 0.1.0.

• The only destructive operation is removal of explicitly selected playlist items; playlist deletion, bulk library removal, history, feedback, upload, subscription, and account-management operations are not exposed.

Security and license

Read SECURITY.md before creating or sharing an authentication file. This project is available under the MIT License.