Provides tools for searching songs via YouTube Data API v3 and returning playback URLs. Supports searching for up to 10 music-category results, playing the best match for voice commands, and retrieving video metadata including title, channel, duration, view count, and embed links.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Xiaozhi YouTube MCP play Numb by Linkin Park"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A complete Model Context Protocol server that lets Xiaozhi or another MCP client search songs through the official YouTube Data API v3 and receive a YouTube playback URL.
youtube_search_song: returns up to 10 Music-category results.
youtube_play_song: returns the best result for direct voice commands.
youtube_get_video: resolves an 11-character video ID to metadata and playback links.
YouTube title, channel, description, thumbnail, ISO-8601 duration, duration in seconds, view count, and embeddability.
stdio transport for desktop/local MCP clients.
Streamable HTTP transport for a hosted Xiaozhi backend.
Docker, Docker Compose, validation, error handling, cache, and tests.
Related MCP server: youtube-mcp
The official YouTube Data API returns video metadata and YouTube URLs; it does not return direct MP3/AAC media streams. This MCP therefore returns:
youtubeUrl: https://www.youtube.com/watch?v=...
embedUrl: https://www.youtube.com/embed/...
Playback requires a YouTube-capable client or an approved handoff to a YouTube player. This project intentionally does not extract or proxy YouTube media streams.
Create or select a Google Cloud project.
Enable YouTube Data API v3.
Create an API key.
Restrict the key to YouTube Data API v3 and, where practical, to your server IP.
cp .env.example .env
# Edit .env and set YOUTUBE_API_KEY
npm install
npm run build
npm startThe default transport is stdio. Never write normal logs to stdout in stdio mode; this server logs startup messages to stderr.
Example MCP client configuration:
{
"mcpServers": {
"youtube": {
"command": "node",
"args": ["/absolute/path/xiaozhi-youtube-mcp/dist/src/index.js"],
"env": {
"YOUTUBE_API_KEY": "YOUR_KEY",
"YOUTUBE_REGION_CODE": "VN",
"YOUTUBE_RELEVANCE_LANGUAGE": "vi"
}
}
}
}After the package is published to npm:
YOUTUBE_API_KEY=YOUR_KEY npx --yes xiaozhi-youtube-mcpFor Streamable HTTP mode:
YOUTUBE_API_KEY=YOUR_KEY MCP_TRANSPORT=http PORT=3000 \
npx --yes xiaozhi-youtube-mcpMCP client configuration using npx:
{
"mcpServers": {
"youtube": {
"command": "npx",
"args": ["--yes", "xiaozhi-youtube-mcp"],
"env": {
"YOUTUBE_API_KEY": "YOUR_KEY",
"YOUTUBE_REGION_CODE": "VN",
"YOUTUBE_RELEVANCE_LANGUAGE": "vi"
}
}
}
}You can also run a GitHub repository before publishing to npm:
YOUTUBE_API_KEY=YOUR_KEY npx --yes github:YOUR_GITHUB_USER/xiaozhi-youtube-mcpFor repeatable production deployments, pin a package version rather than always using the latest version:
npx --yes xiaozhi-youtube-mcp@1.0.0cp .env.example .env
# Set YOUTUBE_API_KEY and MCP_TRANSPORT=http
npm install
npm run build
npm run start:httpEndpoints:
MCP: http://YOUR_SERVER:3000/mcp
Health: http://YOUR_SERVER:3000/health
For public use, put the service behind HTTPS using Nginx, Caddy, Cloudflare Tunnel, or another trusted reverse proxy. Configure the resulting HTTPS MCP URL in the server-side MCP section of your Xiaozhi backend/control panel. The exact UI varies by the Xiaozhi server distribution.
cp .env.example .env
# Edit .env
docker compose up -d --build
curl http://localhost:3000/healthA user says:
Play Numb by Linkin Park
The model should call:
{
"name": "youtube_play_song",
"arguments": {
"query": "Numb Linkin Park",
"officialOnly": true
}
}The structured response contains a playback.url. A Xiaozhi integration that can open YouTube should hand that URL to its player. Otherwise, the assistant can read out or display the selected title and URL.
Variable | Default | Description |
| required | Google API key |
|
|
|
|
| HTTP bind host |
|
| HTTP port |
|
| MCP HTTP route |
|
| ISO two-letter region |
|
| Search relevance language |
|
|
|
|
| Default result count, maximum 10 |
|
| In-memory API response cache |
npm run checkKeep the API key server-side and out of source control.
Apply API restrictions and quota alerts in Google Cloud.
Use HTTPS and network access controls for HTTP deployment.
Add reverse-proxy authentication if the endpoint is publicly reachable.
Cache searches to reduce API usage.
The server filters searches to YouTube video category 10 (Music), requests embeddable videos, and enables configurable SafeSearch.
git init
git add .
git commit -m "Initial Xiaozhi YouTube MCP"
git branch -M main
git remote add origin git@github.com:YOUR_GITHUB_USER/xiaozhi-youtube-mcp.git
git push -u origin main
npm login
npm publishThe npm package name must be available. If xiaozhi-youtube-mcp is already owned by someone else, use a scoped name such as @YOUR_GITHUB_USER/xiaozhi-youtube-mcp, update package.json, and run it with:
npx --yes @YOUR_GITHUB_USER/xiaozhi-youtube-mcpThe included GitHub Actions workflow publishes when you create a GitHub Release. Add an npm automation token as the repository secret NPM_TOKEN, then create a release whose tag matches the version, for example v1.0.0.
Get title, channel, duration, views, thumbnail, and playback URL for a YouTube video ID.
| Name | Required | Description | Default |
|---|---|---|---|
| videoId | Yes | 11-character YouTube video ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks disclosure of behavioral traits such as authentication needs, rate limits, or error handling. The read-only nature is implied but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that includes all critical information: action, resource, and output fields. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter, no output schema needed), the description adequately covers the tool's purpose and return values. However, it lacks information on error scenarios or state changes, which would be needed for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter videoId, which includes a pattern and description. The description adds the list of returned fields, but does not enhance the meaning of the parameter itself beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'YouTube video details', listing specific fields like title, channel, duration, etc. This differentiates it from sibling tools youtube_search_song (search) and youtube_play_song (play).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives, no prerequisites or exclusions. It simply describes what it does without contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the best matching song and return one playback-ready YouTube URL. Prefer this for direct voice commands such as 'play...'
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| regionCode | No | ||
| officialOnly | No | ||
| relevanceLanguage | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions returning a 'playback-ready URL' but does not detail any side effects, authorization requirements, rate limits, or behavior when no match is found. This leaves critical gaps for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences: the first states the core functionality, and the second adds context for usage. Every word earns its place, and the structure is front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, low parameter coverage (0%), and no annotations, the description is minimally adequate. It conveys the primary output (one URL) and usage hint, but lacks details on error handling, best-match criteria, or authentication. It suffices for a simple tool but could be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions exist in the schema. The tool description does not elaborate on any parameter (e.g., query, regionCode, officialOnly, relevanceLanguage), failing to add meaning beyond the raw schema types and constraints. The parameters are mostly self-explanatory, but the description should have provided at least basic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds the best matching song and returns a playback-ready YouTube URL. It distinguishes itself from the sibling 'youtube_search_song' by implying a single best result, and from 'youtube_get_video' by focusing on playback readiness. The mention of voice commands adds context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends this tool for direct voice commands like 'play...', providing clear when-to-use guidance. It implicitly suggests alternatives such as 'youtube_search_song' for broader searches, but does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search YouTube Music-category videos and return playable YouTube URLs. Use this when the user asks to find or play a song.
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | ||
| query | Yes | Song name, artist, lyrics, album, or search phrase | |
| maxResults | No | Number of results, from 1 to 10 | |
| regionCode | No | ISO 3166-1 alpha-2 region, for example VN or US | |
| safeSearch | No | ||
| officialOnly | No | Bias the query toward official audio uploads | |
| relevanceLanguage | No | Language code such as vi or en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions returning 'playable YouTube URLs' but does not disclose limitations like authentication requirements, rate limits, or behavior when no results are found. For a search tool, minimal behavioral context is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core action, and every sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is adequate but missing details such as result format, pagination, or location restrictions. It explains purpose but lacks completeness for an agent to fully understand usage nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 71%, so the schema already documents 5 of 7 parameters. The description adds little extra meaning beyond emphasizing 'playable YouTube URLs.' With moderate coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search YouTube Music-category videos and return playable YouTube URLs' with a specific verb and resource. It also distinguishes from siblings (youtube_play_song and youtube_get_video) by focusing on searching rather than playing or retrieving a single video.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when the user asks to find or play a song,' providing clear context. However, it does not explicitly state when not to use it or mention alternatives, though siblings imply other use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0youtube_get_videoyoutube_play_songyoutube_search_songScored across 3 tools
Tools are distinct: search returns multiple URLs, play returns one best match, get provides metadata. However, search and play both handle song queries, causing slight overlap, but descriptions clarify their usage.
All tools follow a consistent 'youtube_verb_noun' pattern (search_song, play_song, get_video), using underscores and clear action-object format.
Three tools is appropriate for a focused YouTube music MCP server, covering search, playback, and metadata without unnecessary bloat.
Covers core music workflows: searching songs, playing, and getting video details. Minor gaps like playlist or recommendation support exist but are outside stated scope.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
YouTube MCP — wraps the YouTube Data API v3 (BYO API key)
Search YouTube and read video, channel and transcript data as JSON. No Google Cloud project.
YouTube video metadata and channel data by URL or @handle. No API key or quota. Pay per result.
Search YouTube, read video metadata, and fetch transcripts with language preferences