Skip to content

MCP YouTube

This guide enables YouTube integration through the Dockerized YouTube MCP server registered in .mcp.json.

Scope

Current implementation in this repository provides:

  • Docker-only MCP transport
  • Pinned immutable image digest
  • Secrets loaded from local .env
  • Bitwarden-driven hydration of YOUTUBE_API_KEY

Current runtime image: docker.io/node:22-bookworm-slim

Current server source ref: sfiorini/youtube-mcp tag v0.1.12

1. Hydrate YouTube API key from Bitwarden

Expected Bitwarden item:

  • Item name: Youtube API Key
  • Field YOUTUBE_API_KEY: YouTube Data API v3 key

Hydrate local .env from vault fields:

just bw-youtube-key-pull

Or hydrate all MCP runtime secrets at once:

just bw-env-hydrate

This upserts HA_URL, HA_TOKEN, KAGI_API_KEY, and YOUTUBE_API_KEY in local .env.

Note: this repository currently runs YouTube MCP from a pinned fork tag and builds in-container at startup for reliability.

2. Validate MCP wiring

Run from the hermetic Nix shell:

just sync-ai
just mcp-health

Expected summary includes:

  • youtube MCP docker image: docker.io/node@sha256:<digest>

3. Example prompts

In your MCP-capable client, run prompts similar to:

Use the youtube MCP server to search YouTube for "home assistant dashboard tour" and return the top 5 results.

Use the youtube MCP server to get transcript highlights for video ID dQw4w9WgXcQ.

Troubleshooting

  • At least one YouTube API key must be set: run just bw-youtube-key-pull or just bw-env-hydrate, then reload your environment.
  • Startup failures from Docker image pull: run just mcp-health to verify the pinned image is available from your current network.