youtube-mcp-server

你正在研究YouTube上的内容生态，想知道某个领域的头部创作者有哪些，他们的频道规模有多大，最近发布的内容是什么。或者你想分析一个竞争对手频道的视频表现，看看哪些话题最受欢迎。手动在YouTube上搜索、点击、记录，效率很低，而且很难进行系统性的分析。

现在有一个工具可以让AI直接访问YouTube的数据。youtube-mcp-server是一个MCP服务器，它包装了YouTube Data API，让AI能够搜索视频、获取频道信息、提取字幕，甚至通过智能过滤找到符合条件的创作者。配置好之后，你只需要用自然语言提问，比如“找出最近三个月上传过AI编程视频的，粉丝数在1万到10万之间的英文频道”，AI就会自动调用YouTube API，返回符合条件的结果。

项目基本信息

一、项目介绍

youtube-mcp-server是一个基于TypeScript的MCP服务器，它封装了YouTube Data API的多种功能，并通过MCP协议暴露给AI客户端。通过这个服务器，AI可以搜索视频、获取详细信息、提取字幕、查询频道资料、发现创作者、访问播放列表等。

这个服务器提供了十个核心工具，覆盖了YouTube数据访问的主要场景：

视频相关工具

• videos_getVideo：获取单个视频的详细信息，包括标题、描述、观看次数、发布时间等。你可以指定要获取的资源部分（如统计信息、内容详情等）。
• videos_searchVideos：搜索视频。这是一个功能非常强大的工具，支持关键词搜索，还可以按发布时间、频道、排序方式过滤，甚至能根据频道的订阅者数量、最后上传时间等条件来筛选结果。
• transcripts_getTranscript：获取视频的字幕。你可以指定语言，服务器会自动找到可用的字幕并返回文本。

频道相关工具

• channels_getChannel：获取单个频道的详细信息，包括订阅者数、视频数、国家、联系方式等。它还会自动标记频道是“创作者”还是“品牌”。
• channels_getChannels：批量获取多个频道的信息。
• channels_searchChannels：通过名称、句柄或关键词搜索频道。可以按订阅者数量、活跃度、是否为创作者等条件过滤。
• channels_findCreators：一个很有特色的工具。通过一个主题或关键词，找到在视频中提到该主题的创作者频道。也就是说，你搜索“人工智能”，它会找到最近发布过AI相关视频的频道，而不是仅仅匹配频道名称。还可以按订阅者数量、最后上传时间等进一步筛选。
• channels_listVideos：列出某个频道上传的视频列表。

播放列表相关工具

• playlists_getPlaylist：获取播放列表的基本信息。
• playlists_getPlaylistItems：获取播放列表中的所有视频。

这个项目还有一个实用的设计：它支持配置多个YouTube API密钥。当一个密钥的配额用完后，服务器会自动切换到下一个密钥重试请求。这对于需要大量调用API的场景来说，非常有用。

二、核心优势

智能的创作者发现能力

channels_findCreators是项目的亮点。传统的搜索只能匹配频道名称或描述，而这个工具是基于视频内容来发现频道的。你搜索“React 19”，它会在视频字幕和标题中找到讨论React 19的频道，即使频道名字里没有“React”。这对于市场调研和内容发现来说，是一种更有效的思路。

丰富的过滤和排序选项

几乎每个搜索工具都提供了大量的过滤参数。除了基本的发布时间、排序方式，你还可以按频道的订阅者数量范围、最后上传活动时间、是否是创作者频道等条件来筛选。sortBy参数支持按订阅数、独立创作者优先级、最近活跃度等多种排序。这使得你可以非常精准地定位目标内容或频道。

多API密钥的轮换支持

YouTube Data API有每日配额限制。这个服务器允许你配置最多三个API密钥，当一个密钥配额耗尽时，它会自动用下一个密钥重试。这对于需要大量数据采集的应用场景来说，是一个很实用的容错设计，避免了因配额用尽而导致服务中断。

结构化的元数据增强

channels_getChannel返回的内容不仅包含YouTube API的标准字段，还增加了normalizedMetadata，其中包含国家、默认语言、加入日期、邮箱、联系方式链接，以及一个启发式的分类（创作者 vs 品牌）。这些增强信息对于做频道分析、联系创作者非常有帮助。

灵活的部署方式

你可以通过npm全局安装，也可以用npx直接运行而不安装，还可以使用Docker容器化部署。支持stdio和HTTP两种传输方式，兼容各种MCP客户端。

三、适用场景

内容创作者的市场研究

如果你是一个YouTube创作者，想研究某个细分领域。你可以用channels_findCreators搜索“烘焙教程”，找到最近活跃的烘焙频道，然后通过channels_listVideos分析他们的热门视频主题、发布时间和观看量关系，从而优化自己的内容策略。

品牌营销的KOL发现

品牌方想在YouTube上找推广合作。可以用channels_searchChannels或channels_findCreators，按订阅者数量范围、最后上传时间、是否为创作者等条件筛选。比如“找到订阅量在5万到20万之间，最近一个月有上传，且不是品牌官方号的科技类创作者”。

AI训练数据的筛选

如果你需要收集大量的YouTube字幕用于训练语言模型，可以用videos_searchVideos和transcripts_getTranscript组合。你可以通过过滤条件，比如“过去一年发布的、时长10-30分钟的、英文的科技类访谈”，来精准地收集符合你训练数据分布的视频。

教育研究与分析

教育工作者或研究者可以用这个工具来分析某个主题的公开视频资源。例如搜索“量子计算”的相关视频，获取它们的描述、时长、上传日期，然后用脚本生成一个带链接的课程资源列表。

社交聆听与话题监测

公关公司可以监测特定关键词在YouTube上的讨论。通过videos_searchVideos按日期排序，可以实时跟踪新发布的视频，了解公众对某个话题的反应和讨论方向。

频道运营的数据分析

频道管理员可以用channels_listVideos定期获取自己频道的视频列表，结合获取到的观看量、评论数等数据，在本地做趋势分析，而不必每次都登录YouTube Studio。

四、安装教程

前置准备

在使用之前，你需要一个YouTube Data API密钥。访问Google Cloud Console，创建一个新项目（或选择现有项目），启用YouTube Data API v3，然后创建凭据（API密钥）。注意：这个API密钥没有限制，但你需要为它设置配额限制来避免意外的高额费用。免费配额每天有10,000个单位，大多数搜索请求消耗100个单位。

你还需要一个支持MCP协议的AI客户端。本教程以Claude Desktop和Cursor为例。

方式一：全局安装（推荐）

在终端中运行以下命令：

npm install -g zubeid-youtube-mcp-server

安装完成后，配置Claude Desktop。找到配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置，将your_primary_youtube_api_key替换为你的真实API密钥。如果你有多个密钥，可以都配置上：

{
  "mcpServers": {
    "zubeid-youtube-mcp-server": {
      "command": "zubeid-youtube-mcp-server",
      "env": {
        "YOUTUBE_API_KEY": "你的主API密钥",
        "YOUTUBE_API_KEY2": "你的备用API密钥",
        "YOUTUBE_API_KEY3": "你的第三API密钥"
      }
    }
  }
}

方式二：通过npx运行（无需安装）

如果你不想全局安装，可以通过npx直接运行。在Claude Desktop的配置中使用以下内容：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "zubeid-youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "你的API密钥"
      }
    }
  }
}

方式三：配置到Cursor

在项目的根目录下创建或编辑.cursor/mcp.json：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "zubeid-youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "你的API密钥"
      }
    }
  }
}

方式四：使用Docker（适合服务器部署）

首先克隆项目并构建镜像：

git clone https://github.com/ZubeidHendricks/youtube-mcp-server.git
cd youtube-mcp-server
docker build -t youtube-mcp-server .

然后运行容器：

docker run --rm -p 8088:8088 youtube-mcp-server

默认情况下，服务器会以HTTP模式运行在http://localhost:8088/mcp。你可以在MCP客户端中将此URL配置为Streamable HTTP类型的服务器。

方式五：通过Smithery一键安装（Claude Desktop）

在终端中运行：

npx -y @smithery/cli install @ZubeidHendricks/youtube --client claude

验证安装

配置完成后，重启Claude Desktop。然后试着问：

“Use the YouTube MCP to get information about video with ID dQw4w9WgXcQ”

如果配置成功，AI会调用videos_getVideo工具并返回视频的详细信息。

五、使用示例

配置完成后，你可以用自然语言让AI执行各种YouTube数据查询。

示例一：获取视频信息

“Get detailed information about this YouTube video: https://www.youtube.com/watch?v=abc123”

AI会提取视频ID，然后调用videos_getVideo，返回标题、观看次数、点赞数、发布时间等。

示例二：搜索视频并过滤

“Search for videos about 'machine learning' published in the last month, from channels with between 10k and 100k subscribers, and return the top 5 results.”

AI会调用videos_searchVideos，设置publishedAfter为一个月前，并使用channelMinSubscribers和channelMaxSubscribers参数。返回的结果会包括每个视频的标题、频道名、观看次数。

示例三：获取视频字幕

“Get the English transcript of the video with ID xyz789, and then summarize the main points.”

AI会调用transcripts_getTranscript获取字幕文本，然后基于这个文本做摘要。注意：不是所有视频都有字幕，有些需要作者开启。

示例四：搜索创作者频道

“Find YouTube channels that have recently uploaded videos about 'indie game development'. Only include channels with more than 50,000 subscribers and that have uploaded within the last 3 months.”

这是channels_findCreators的典型用法。它会先搜索相关视频，然后找出发布这些视频的频道，再根据订阅者和最后上传时间进行过滤。返回的是频道列表，而不是视频列表。

示例五：分析频道的视频表现

“Get the last 20 videos from channel UCxyz123, extract their titles, view counts, and publish dates, then tell me which topic got the most views.”

AI会调用channels_listVideos获取视频列表，然后对返回的数据进行分析。你可以进一步要求“Plot the view count over time”，但那是AI的能力，不是这个工具的直接功能。

示例六：播放列表分析

“Get all videos in the playlist PLxyz456, then find the average view count and the most commented video.”

AI会先用playlists_getPlaylistItems获取视频ID列表，然后可能需要多次调用videos_getVideo来获取每个视频的统计信息（注意API配额）。最后汇总计算。

六、常见问题

API Key无效或配额不足

请确认你的API密钥是从Google Cloud Console正确生成的，并且YouTube Data API v3已经启用。免费配额是每天10,000个单位。如果配额用尽，服务器会尝试使用备用的API密钥（如果配置了）。你可以在Google Cloud Console中查看配额使用情况。

搜索返回的结果太少或不符合预期

检查你的过滤条件是否过于严格。例如channelMinSubscribers设置为100,000，但相关频道的订阅者可能都低于这个值。另外，YouTube API本身对某些搜索有默认限制。尝试放宽条件，或者调整order和sortBy参数。

channels_findCreators的发现结果不准确

这个工具是基于“出现在相关视频中”来发现频道的，而不是基于频道的自我描述。如果某个频道的视频标题和描述中没有出现你的关键词，它可能不会被发现。另外，sampleVideosPerChannel参数控制每个频道返回的示例视频数量，默认值可能较小，可以调高这个值来获得更多的匹配证据。

获取字幕返回空或错误

不是所有视频都有字幕。字幕是由上传者提供的，或者由YouTube自动生成（但自动生成可能不准确，且不一定总是可用）。如果视频有字幕，检查你指定的语言代码是否正确（如'en'、'zh-Hans'）。你可以先用videos_getVideo获取视频的内容详情，看它是否有字幕轨道。

API配额消耗过快

每次videos_searchVideos大约消耗100个单位，每次videos_getVideo消耗1-5个单位（取决于请求的parts）。批量操作时配额会快速消耗。建议：缓存常用数据，合理设置maxResults，避免不必要的重复查询。如果使用多个API密钥，设置好轮换策略。

在Docker中运行时如何传入API密钥

Docker构建时会读取项目目录下的.env文件。你可以在克隆项目后，创建.env文件并填入YOUTUBE_API_KEY=你的密钥，然后再构建镜像。或者在运行容器时通过-e参数传入环境变量，覆盖构建时的值：

docker run --rm -p 8088:8088 -e YOUTUBE_API_KEY="你的密钥" youtube-mcp-server

七、总结

youtube-mcp-server是一个专注于YouTube数据访问的MCP服务器。它的工具集覆盖了视频、频道、播放列表和字幕等核心数据，而且提供了很多超越官方API的智能过滤和发现能力。

我特别喜欢channels_findCreators这个工具。它改变了搜索逻辑：从“频道说自己是什么”到“频道实际做了什么”。这对于做内容研究、竞争分析或KOL发现来说，提供了一种更本质的视角。项目的作者显然很理解研究者真正需要的是什么，而不是简单地封装API。

多API密钥轮换也是一个很实用的功能。YouTube的配额限制是很多数据采集项目的瓶颈，这个设计让用户可以组合多个免费配额，或者在不同项目之间隔离配额，提高了稳定性。

当然，这个项目还有一些可以改进的地方。目前没有提供视频评论、点赞等交互数据的写入能力（比如发布评论、点赞），主要是读取操作。另外，对于需要大规模数据采集的场景，每月的API配额成本需要仔细规划。但考虑到这是一个免费开源的工具，它已经做得相当出色了。

如果你是内容创作者、营销人员、研究者，或者任何需要从YouTube获取结构化数据的人，youtube-mcp-server值得你尝试。它让AI能够深入理解视频生态，帮你从海量内容中发现有价值的规律和机会。