YouTube MCP Server for Windsurf: Setup & Config

What you can do with YouTube in Windsurf

A research-focused YouTube interface with transcripts, filtered creator discovery, and quota fallback.

• Retrieve transcripts for assistant-led content review.
• Inspect channel uploads and playlist contents.

Before you start: YouTube in Windsurf

• Node.js and npx
• At least one YouTube Data API key
• An MCP-compatible client

Uses the README's npx configuration, not the different package in the structured config hint. YOUTUBE_API_KEY2 and YOUTUBE_API_KEY3 are optional fallback keys. YOUTUBE_TRANSCRIPT_LANG optionally changes the default transcript language. Docker defaults to HTTP at http://localhost:8088/mcp.

YouTube Windsurf configuration

1. Choose Windsurf configuration scope

   For YouTube MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add YouTube MCP Server to Windsurf

   Use the youtube-mcp-server entry below in mcpServers. Keep YouTube MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check YouTube MCP Server in Windsurf

   YouTube MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "youtube-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "zubeid-youtube-mcp-server"
      ],
      "env": {
        "YOUTUBE_API_KEY": "<YouTube Data API key>"
      }
    }
  }
}

YouTube tools available to Windsurf

YouTube's stored tool list documents 10 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

videos_getVideo

After refreshing YouTube in Windsurf settings, check Cascade's tool list for videos_getVideo.

videos_searchVideos

After refreshing YouTube in Windsurf settings, check Cascade's tool list for videos_searchVideos.

transcripts_getTranscript

After refreshing YouTube in Windsurf settings, check Cascade's tool list for transcripts_getTranscript.

channels_getChannel

After refreshing YouTube in Windsurf settings, check Cascade's tool list for channels_getChannel.

Inspect a channel with latest-upload and normalized metadata fields.

channels_getChannels

After refreshing YouTube in Windsurf settings, check Cascade's tool list for channels_getChannels.

Retrieve several channels, optionally including their latest upload dates.

channels_searchChannels

After refreshing YouTube in Windsurf settings, check Cascade's tool list for channels_searchChannels.

channels_findCreators

After refreshing YouTube in Windsurf settings, check Cascade's tool list for channels_findCreators.

channels_listVideos

After refreshing YouTube in Windsurf settings, check Cascade's tool list for channels_listVideos.

List videos belonging to a specified channel.

playlists_getPlaylist

After refreshing YouTube in Windsurf settings, check Cascade's tool list for playlists_getPlaylist.

Inspect details for a selected playlist.

playlists_getPlaylistItems

After refreshing YouTube in Windsurf settings, check Cascade's tool list for playlists_getPlaylistItems.

Retrieve videos contained in a playlist.

YouTube: full stored tool descriptions

Troubleshooting YouTube in Windsurf

• Check npx zubeid-youtube-mcp-server (Node.js/npm) on the machine running Windsurf's MCP integration for YouTube MCP Server; refresh MCP and inspect Cascade's tools.
• Check YOUTUBE_API_KEY for YouTube MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• YouTube MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: At least one YouTube Data API key is required.
• Known limitation: Creator-only filtering uses heuristics rather than a guaranteed classification.
• Known limitation: The Docker build can include credentials from its copied environment file.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions