2026/9/17 17:29:47
FEATURED · 精选文章 
Klavis 仓库中 YouTube MCP Server 的开发指南架构、工具注册与构建实践【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本篇文章以mcp_servers/youtube_toolathlon/CLAUDE.md为核心骨架结合同目录下的源码、配置与使用文档系统讲解这套 YouTube MCPModel Context Protocol服务器的开发命令、环境变量、服务化架构、9 个 MCP 工具的注册与调用链路以及从npm install到npm start的完整构建流程。读完本文你将掌握如何在本仓库中启动、开发、构建并部署一个面向 AI 语言模型的 YouTube 集成 MCP Server并理解其懒加载 服务分层的底层实现原理。一、文档定位与开发起点CLAUDE.md 是仓库为该目录提供的开发指引专门服务于使用 Claude Code 等工具在此代码库中进行开发、调试和构建的场景。它本身不是一份面向终端用户的安装说明而是一份面向开发者的工程手册涵盖三个核心部分开发命令依赖安装、构建、热重载、启动与发布前的完整命令链环境变量必填的YOUTUBE_API_KEY与可选的YOUTUBE_TRANSCRIPT_LANG项目架构入口、服务层、类型定义、MCP 工具注册模式与构建配置。因此本文的读者定位是要在本仓库中开发或二次构建该 MCP Server 的工程师而终端用户的安装与配置方式如 Claude Desktop、VS Code 集成则作为附录补充详见同目录的 README.md。二、开发命令从安装到发布CLAUDE.md 给出了完整的生命周期命令。所有命令都在mcp_servers/youtube_toolathlon/目录下执行与 package.json 中的scripts字段一一对应命令作用底层实现package.jsonnpm install安装全部依赖根据dependencies与devDependencies拉取npm run build编译 TypeScript 到dist/tscnpm run dev开发模式改动自动重建并重启nodemon --exec npm run build npm start --ext tsnpm start启动服务器需先构建node ./dist/index.jsnpm run prepublishOnly发布前准备自动执行构建npm run build值得注意的细节npm start要求先构建CLAUDE.md 明确强调 Start the server (requires build first)因为启动脚本直接指向编译产物dist/index.js如果跳过npm run build会因产物缺失而失败npm run dev是复合命令它先用 nodemon 监听.ts文件每次改动触发npm run build重新编译再npm start重启进程实现改代码 → 自动重建 → 自动重启的开发闭环发布安全网prepublishOnly会在执行npm publish前自动跑一次tsc避免把未编译的源码发布出去。构建所需的编译器配置见 tsconfig.json目标ES2022、模块系统ESNext、产物输出到./dist、源码根目录为./src并显式exclude了node_modules与src/functions/**/*——这正是 CLAUDE.md 所说 Thefunctions/directory contains additional functionality that is excluded from the main build 的配置依据。三、环境变量配置CLAUDE.md 列出两个环境变量而结合 auth.ts 与 index.ts 的源码还可以补充另外三个可选变量变量必填默认值说明YOUTUBE_API_KEY是无YouTube Data API v3 密钥所有依赖 YouTube API 的操作都需要它YOUTUBE_TRANSCRIPT_LANG否en默认字幕语言作用于字幕抓取服务PORT否5000HTTP 模式监听端口见 index.tsACCESS_TOKEN否空访问令牌stdio/本地测试时的兜底值AUTH_DATA否空Base64 编码的 JSON 认证数据可携带access_token与api_key从 auth.ts 的getApiKey()可以看到密钥的解析优先级先取请求上下文AsyncLocalStorage中由 HTTP 头x-auth-data携带的api_key再回退到环境变量YOUTUBE_API_KEY。这意味着该服务器同时支持两种鉴权方式stdio 模式本地 CLI直接设置环境变量YOUTUBE_API_KEYHTTP 模式Streamable HTTP客户端可在请求头x-auth-data中传入 Base64 编码的 JSON如{api_key: ...}由服务端解码后注入当前请求上下文。四、项目架构服务化分层CLAUDE.md 明确指出这是一个service-oriented pattern面向服务的架构。整体结构如下mcp_servers/youtube_toolathlon/ ├── src/ │ ├── index.ts # HTTP 服务器入口Express Streamable HTTP │ ├── cli.ts # CLI 二进制入口stdio 传输 │ ├── server.ts # MCP Server 初始化与工具注册 │ ├── auth.ts # API Key / Token 解析 │ ├── types.ts # 全部参数 TypeScript 接口 │ ├── services/ # 业务逻辑层 │ │ ├── video.ts # VideoService │ │ ├── transcript.ts # TranscriptService │ │ ├── channel.ts # ChannelService │ │ ├── playlist.ts # PlaylistService │ │ └── listManager.ts# 频道视频列表会话管理器 │ ├── utils/ │ │ └── dataUtils.ts # 缩略图清理、错误信息工具 │ ├── types/ # 第三方库类型声明global-types、google、youtube-transcript、ytdl │ └── functions/ # 附加功能被 tsconfig 排除在主构建之外各职责划分如下入口层index.ts 是主服务器入口基于 Express 提供POST /mcp端点使用 MCP SDK 的StreamableHTTPServerTransport处理请求cli.ts 则基于StdioServerTransport提供标准输入输出模式两者都复用createMcpServer()工厂函数组装层server.ts 创建 MCPServer实例声明tools能力注册ListToolsRequestSchema与CallToolRequestSchema两个请求处理器并实例化四个服务对象业务层src/services/下的四个服务类分别封装视频、字幕、频道、播放列表的 YouTube 操作类型层types.ts 集中定义所有工具入参的 TypeScript 接口例如VideoParams、SearchParams、TranscriptParams、ChannelVideosParams、PlaylistItemsParams等。五、MCP 工具架构注册与调用链路CLAUDE.md 中提到服务器暴露的工具遵循{category}_{action}命名模式。需要说明的是文档列举了 7 个工具而对照 server.ts 的ListToolsRequestSchema实现当前源码实际注册了9 个工具在文档所列基础上增加了channels_navigateList与playlists_searchPlaylists按类别整理如下5.1 视频类Video工具名必填参数可选参数功能videos_getVideovideoIdparts获取视频详细信息默认parts为snippet、contentDetails、statisticsvideos_searchVideosquerymaxResults搜索视频默认返回 10 条5.2 字幕类Transcript工具名必填参数可选参数功能transcripts_getTranscriptvideoIdlanguage获取视频字幕语言默认取YOUTUBE_TRANSCRIPT_LANG未设置时为en5.3 频道类Channel工具名必填参数可选参数功能channels_getChannelchannelId无获取频道信息snippet、statistics、contentDetailschannels_listVideoschannelIdmaxResults最大 20默认 20、sortOrdernewest/oldest/popular新建一个频道视频列表会话返回首页数据与listIdchannels_navigateListlistId、page1 起始无在既有会话内翻页/跳页5.4 播放列表类Playlist工具名必填参数可选参数功能playlists_getPlaylistplaylistId无获取播放列表信息playlists_getPlaylistItemsplaylistIdmaxResults默认 50获取播放列表中的视频并合并视频详情playlists_searchPlaylistsquerymaxResults默认 10搜索播放列表5.5 调用链路从 MCP 请求到 YouTube API在 server.ts 的CallToolRequestSchema处理器中工具名通过switch分发到对应服务方法例如videos_getVideo→videoService.getVideo(args)transcripts_getTranscript→transcriptService.getTranscript(args)channels_listVideos→channelService.listVideos(args)返回listIdchannels_navigateList→channelService.navigateList(args)携带listId与页码。服务方法内部再调用googleapis的 YouTube Data API v3 客户端最终结果统一以content[0].textJSON 字符串的形式返回给 LLM工具执行出错时则返回isError: true的错误文本。六、服务层模式懒加载与统一错误处理CLAUDE.md 强调所有服务使用lazy initialization懒加载YouTube API 客户端不会在服务器启动时初始化而是等到工具真正被调用时才创建从而把 API Key 校验推迟到调用时刻避免服务器能启动但所有工具都报错的割裂体验。以 video.ts 的initialize()为例private initialize() { if (this.initialized) return; const apiKey getApiKey(); if (!apiKey) { throw new Error(YouTube API key is missing. Provide it via YOUTUBE_API_KEY env var or x-auth-data header.); } this.youtube google.youtube({ version: v3, auth: apiKey, }); this.initialized true; }这里有两个工程细节值得学习幂等初始化if (this.initialized) return;保证google.youtube()客户端只创建一次后续调用直接复用密钥缺失即抛错API Key 缺失时抛出明确错误提示通过YOUTUBE_API_KEY环境变量或x-auth-data头提供错误信息会经 dataUtils.ts 的createErrorMessage()包装后返回给调用方。一个例外是 transcript.ts字幕服务基于youtube-transcript库无需 API Key因此其initialize()不做任何密钥校验注释中也明确说明 No API key needed for transcripts。所有服务方法统一遵循 try/catch 包裹模式成功时返回清洗后的数据通过removeThumbnails()剔除体积较大的缩略图字段失败时抛出统一格式的错误信息。七、构建配置与产物CLAUDE.md 的 Build Configuration 部分总结了关键编译参数与 tsconfig.json 一致TypeScript 目标ES2022模块系统ESNext即 ES Modulestype: module同时写在 package.json 中导入规范ES Modules 要求在相对导入中使用.js扩展名如from ./server.js这与源码中的写法一致输出目录./dist源码根目录./src发布入口dist/index.js服务器与dist/cli.jsCLI 二进制后者通过 package.json 的bin字段映射为全局命令zubeid-youtube-mcp-server构建边界include仅包含src/services、src/utils、入口与类型文件exclude掉src/functions/**/*确保附加功能不进入主构建。八、两种运行模式stdio 与 Streamable HTTPCLAUDE.md 提到两个入口文件二者分别对应 MCP 的两种典型传输方式模式一stdiocli.tsimport { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { createMcpServer } from ./server.js; const server createMcpServer(); const transport new StdioServerTransport(); server.connect(transport)...通过标准输入输出与父进程如 Claude Desktop、VS Code通信适用于本地桌面集成也是 README.md 中 Claude Desktop / npx 配置使用的模式。模式二Streamable HTTPindex.ts基于 Express 暴露POST /mcp端点使用StreamableHTTPServerTransport。处理流程为从请求头提取认证数据extractAuthData创建 MCP Server 与 transport 并connect通过asyncLocalStorage.run()把认证信息注入当前异步上下文再handleRequest请求关闭时清理 transport 与 server。同时GET /mcp与DELETE /mcp返回 405Method Not Allowed符合 Streamable HTTP 仅允许 POST 的语义。默认监听PORT未设置时为 5000可用于远程部署场景如云端 Agent 平台。九、纵深实现频道视频列表的分页会话机制CLAUDE.md 只提及ChannelService负责频道信息与视频列表但仓库源码中隐藏着一个值得单独剖析的实现listManager.ts 为频道视频列表提供了有状态的分页会话机制。核心设计如下会话创建channels_listVideos调用时先通过channels.list拿到频道的 uploads 播放列表 ID 与总视频数再调用ListManager.createSession()生成listId格式为list_ 8 字节随机十六进制并缓存maxResults、sortOrder、totalPages等元信息Token 缓存会话内部用Mapnumber, string记录页码 → nextPageToken首次调用pageTokens new Map([[1, ]])第一页无 token跳页导航channels_navigateList只需携带listId与目标页码。若目标页 token 未缓存calculatePageToken()会逐页翻越前序页面补齐 token 并缓存见 channel.ts会话过期会话超时时间为 30 分钟getSession()检查时发现过期即删除单例构造器还每 10 分钟执行一次cleanupExpiredSessions()清理过期会话避免内存泄漏排序策略sortVideos()支持newest上传列表默认顺序、oldest反转、popular按 viewCount 降序三种排序。这一机制让 LLM 可以在一次对话中创建列表会话 → 翻页 → 跳页而无需重复请求整页数据是值得参考的 MCP 有状态工具设计模式。十、关键依赖与部署使用CLAUDE.md 列出了四大核心依赖在 package.json 中均可确认依赖版本仓库内用途modelcontextprotocol/sdk^1.1.1MCP 协议实现Server、stdio/Streamable HTTP transportgoogleapis^129.0.0YouTube Data API v3 客户端youtube-transcript1.0.6字幕抓取无需 API Keyytdl-core^4.11.5YouTube 视频信息抓取部署与客户端接入方式以 README.md 为准主要包括Claude Desktop 全局安装npm install -g zubeid-youtube-mcp-server再在claude_desktop_config.json的mcpServers中配置command与YOUTUBE_API_KEYnpx 免安装模式command: npx, args: [-y, zubeid-youtube-mcp-server]VS Code 集成在 User Settings (JSON) 或工作区.vscode/mcp.json中声明mcp.servers.youtube支持用${input:apiKey}交互式注入密钥容器化部署目录内提供 Dockerfile可通过环境变量注入YOUTUBE_API_KEY后以 HTTP 模式对外提供服务。十一、开发注意事项小结基于以上源码分析在仓库中进行二次开发时有几点需要留意先构建再启动npm start依赖dist/产物日常迭代请使用npm run dev获得自动重建重启体验新增工具必须双注册在 server.ts 中既要向ListToolsRequestSchema的tools数组添加工具声明含 JSON Schema 入参定义也要在CallToolRequestSchema的switch分支中补充调用逻辑缺一不可新增服务遵循既定模式复制VideoService的懒加载initialize()与 try/catch 错误包装结构并复用removeThumbnails、createErrorMessage工具函数保持代码风格一致参数类型集中管理所有工具入参的 TypeScript 接口统一维护在 types.ts避免在服务间散落重复定义functions/目录不进主构建需要独立分发的附加功能应放在该目录并自行管理构建流程tsconfig 的exclude已将其排除。综上本仓库中的 YouTube MCP Server 以懒加载服务 双入口stdio/HTTP 统一工具注册的工程范式为 AI 语言模型提供了视频查询、字幕抓取、频道管理与播放列表检索的标准化能力。开发者既可以基于npm run dev快速迭代也可以对照server.ts的注册模式扩展属于自己的新工具。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Klavis 仓库中 YouTube MCP Server 的开发指南：架构、工具注册与构建实践
Klavis 仓库中 YouTube MCP Server 的开发指南架构、工具注册与构建实践【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本篇文章以mcp_servers/youtube_toolathlon/CLAUDE.md为核心骨架结合同目录下的源码、配置与使用文档系统讲解这套 YouTube MCPModel Context Protocol服务器的开发命令、环境变量、服务化架构、9 个 MCP 工具的注册与调用链路以及从npm install到npm start的完整构建流程。读完本文你将掌握如何在本仓库中启动、开发、构建并部署一个面向 AI 语言模型的 YouTube 集成 MCP Server并理解其懒加载 服务分层的底层实现原理。一、文档定位与开发起点CLAUDE.md 是仓库为该目录提供的开发指引专门服务于使用 Claude Code 等工具在此代码库中进行开发、调试和构建的场景。它本身不是一份面向终端用户的安装说明而是一份面向开发者的工程手册涵盖三个核心部分开发命令依赖安装、构建、热重载、启动与发布前的完整命令链环境变量必填的YOUTUBE_API_KEY与可选的YOUTUBE_TRANSCRIPT_LANG项目架构入口、服务层、类型定义、MCP 工具注册模式与构建配置。因此本文的读者定位是要在本仓库中开发或二次构建该 MCP Server 的工程师而终端用户的安装与配置方式如 Claude Desktop、VS Code 集成则作为附录补充详见同目录的 README.md。二、开发命令从安装到发布CLAUDE.md 给出了完整的生命周期命令。所有命令都在mcp_servers/youtube_toolathlon/目录下执行与 package.json 中的scripts字段一一对应命令作用底层实现package.jsonnpm install安装全部依赖根据dependencies与devDependencies拉取npm run build编译 TypeScript 到dist/tscnpm run dev开发模式改动自动重建并重启nodemon --exec npm run build npm start --ext tsnpm start启动服务器需先构建node ./dist/index.jsnpm run prepublishOnly发布前准备自动执行构建npm run build值得注意的细节npm start要求先构建CLAUDE.md 明确强调 Start the server (requires build first)因为启动脚本直接指向编译产物dist/index.js如果跳过npm run build会因产物缺失而失败npm run dev是复合命令它先用 nodemon 监听.ts文件每次改动触发npm run build重新编译再npm start重启进程实现改代码 → 自动重建 → 自动重启的开发闭环发布安全网prepublishOnly会在执行npm publish前自动跑一次tsc避免把未编译的源码发布出去。构建所需的编译器配置见 tsconfig.json目标ES2022、模块系统ESNext、产物输出到./dist、源码根目录为./src并显式exclude了node_modules与src/functions/**/*——这正是 CLAUDE.md 所说 Thefunctions/directory contains additional functionality that is excluded from the main build 的配置依据。三、环境变量配置CLAUDE.md 列出两个环境变量而结合 auth.ts 与 index.ts 的源码还可以补充另外三个可选变量变量必填默认值说明YOUTUBE_API_KEY是无YouTube Data API v3 密钥所有依赖 YouTube API 的操作都需要它YOUTUBE_TRANSCRIPT_LANG否en默认字幕语言作用于字幕抓取服务PORT否5000HTTP 模式监听端口见 index.tsACCESS_TOKEN否空访问令牌stdio/本地测试时的兜底值AUTH_DATA否空Base64 编码的 JSON 认证数据可携带access_token与api_key从 auth.ts 的getApiKey()可以看到密钥的解析优先级先取请求上下文AsyncLocalStorage中由 HTTP 头x-auth-data携带的api_key再回退到环境变量YOUTUBE_API_KEY。这意味着该服务器同时支持两种鉴权方式stdio 模式本地 CLI直接设置环境变量YOUTUBE_API_KEYHTTP 模式Streamable HTTP客户端可在请求头x-auth-data中传入 Base64 编码的 JSON如{api_key: ...}由服务端解码后注入当前请求上下文。四、项目架构服务化分层CLAUDE.md 明确指出这是一个service-oriented pattern面向服务的架构。整体结构如下mcp_servers/youtube_toolathlon/ ├── src/ │ ├── index.ts # HTTP 服务器入口Express Streamable HTTP │ ├── cli.ts # CLI 二进制入口stdio 传输 │ ├── server.ts # MCP Server 初始化与工具注册 │ ├── auth.ts # API Key / Token 解析 │ ├── types.ts # 全部参数 TypeScript 接口 │ ├── services/ # 业务逻辑层 │ │ ├── video.ts # VideoService │ │ ├── transcript.ts # TranscriptService │ │ ├── channel.ts # ChannelService │ │ ├── playlist.ts # PlaylistService │ │ └── listManager.ts# 频道视频列表会话管理器 │ ├── utils/ │ │ └── dataUtils.ts # 缩略图清理、错误信息工具 │ ├── types/ # 第三方库类型声明global-types、google、youtube-transcript、ytdl │ └── functions/ # 附加功能被 tsconfig 排除在主构建之外各职责划分如下入口层index.ts 是主服务器入口基于 Express 提供POST /mcp端点使用 MCP SDK 的StreamableHTTPServerTransport处理请求cli.ts 则基于StdioServerTransport提供标准输入输出模式两者都复用createMcpServer()工厂函数组装层server.ts 创建 MCPServer实例声明tools能力注册ListToolsRequestSchema与CallToolRequestSchema两个请求处理器并实例化四个服务对象业务层src/services/下的四个服务类分别封装视频、字幕、频道、播放列表的 YouTube 操作类型层types.ts 集中定义所有工具入参的 TypeScript 接口例如VideoParams、SearchParams、TranscriptParams、ChannelVideosParams、PlaylistItemsParams等。五、MCP 工具架构注册与调用链路CLAUDE.md 中提到服务器暴露的工具遵循{category}_{action}命名模式。需要说明的是文档列举了 7 个工具而对照 server.ts 的ListToolsRequestSchema实现当前源码实际注册了9 个工具在文档所列基础上增加了channels_navigateList与playlists_searchPlaylists按类别整理如下5.1 视频类Video工具名必填参数可选参数功能videos_getVideovideoIdparts获取视频详细信息默认parts为snippet、contentDetails、statisticsvideos_searchVideosquerymaxResults搜索视频默认返回 10 条5.2 字幕类Transcript工具名必填参数可选参数功能transcripts_getTranscriptvideoIdlanguage获取视频字幕语言默认取YOUTUBE_TRANSCRIPT_LANG未设置时为en5.3 频道类Channel工具名必填参数可选参数功能channels_getChannelchannelId无获取频道信息snippet、statistics、contentDetailschannels_listVideoschannelIdmaxResults最大 20默认 20、sortOrdernewest/oldest/popular新建一个频道视频列表会话返回首页数据与listIdchannels_navigateListlistId、page1 起始无在既有会话内翻页/跳页5.4 播放列表类Playlist工具名必填参数可选参数功能playlists_getPlaylistplaylistId无获取播放列表信息playlists_getPlaylistItemsplaylistIdmaxResults默认 50获取播放列表中的视频并合并视频详情playlists_searchPlaylistsquerymaxResults默认 10搜索播放列表5.5 调用链路从 MCP 请求到 YouTube API在 server.ts 的CallToolRequestSchema处理器中工具名通过switch分发到对应服务方法例如videos_getVideo→videoService.getVideo(args)transcripts_getTranscript→transcriptService.getTranscript(args)channels_listVideos→channelService.listVideos(args)返回listIdchannels_navigateList→channelService.navigateList(args)携带listId与页码。服务方法内部再调用googleapis的 YouTube Data API v3 客户端最终结果统一以content[0].textJSON 字符串的形式返回给 LLM工具执行出错时则返回isError: true的错误文本。六、服务层模式懒加载与统一错误处理CLAUDE.md 强调所有服务使用lazy initialization懒加载YouTube API 客户端不会在服务器启动时初始化而是等到工具真正被调用时才创建从而把 API Key 校验推迟到调用时刻避免服务器能启动但所有工具都报错的割裂体验。以 video.ts 的initialize()为例private initialize() { if (this.initialized) return; const apiKey getApiKey(); if (!apiKey) { throw new Error(YouTube API key is missing. Provide it via YOUTUBE_API_KEY env var or x-auth-data header.); } this.youtube google.youtube({ version: v3, auth: apiKey, }); this.initialized true; }这里有两个工程细节值得学习幂等初始化if (this.initialized) return;保证google.youtube()客户端只创建一次后续调用直接复用密钥缺失即抛错API Key 缺失时抛出明确错误提示通过YOUTUBE_API_KEY环境变量或x-auth-data头提供错误信息会经 dataUtils.ts 的createErrorMessage()包装后返回给调用方。一个例外是 transcript.ts字幕服务基于youtube-transcript库无需 API Key因此其initialize()不做任何密钥校验注释中也明确说明 No API key needed for transcripts。所有服务方法统一遵循 try/catch 包裹模式成功时返回清洗后的数据通过removeThumbnails()剔除体积较大的缩略图字段失败时抛出统一格式的错误信息。七、构建配置与产物CLAUDE.md 的 Build Configuration 部分总结了关键编译参数与 tsconfig.json 一致TypeScript 目标ES2022模块系统ESNext即 ES Modulestype: module同时写在 package.json 中导入规范ES Modules 要求在相对导入中使用.js扩展名如from ./server.js这与源码中的写法一致输出目录./dist源码根目录./src发布入口dist/index.js服务器与dist/cli.jsCLI 二进制后者通过 package.json 的bin字段映射为全局命令zubeid-youtube-mcp-server构建边界include仅包含src/services、src/utils、入口与类型文件exclude掉src/functions/**/*确保附加功能不进入主构建。八、两种运行模式stdio 与 Streamable HTTPCLAUDE.md 提到两个入口文件二者分别对应 MCP 的两种典型传输方式模式一stdiocli.tsimport { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { createMcpServer } from ./server.js; const server createMcpServer(); const transport new StdioServerTransport(); server.connect(transport)...通过标准输入输出与父进程如 Claude Desktop、VS Code通信适用于本地桌面集成也是 README.md 中 Claude Desktop / npx 配置使用的模式。模式二Streamable HTTPindex.ts基于 Express 暴露POST /mcp端点使用StreamableHTTPServerTransport。处理流程为从请求头提取认证数据extractAuthData创建 MCP Server 与 transport 并connect通过asyncLocalStorage.run()把认证信息注入当前异步上下文再handleRequest请求关闭时清理 transport 与 server。同时GET /mcp与DELETE /mcp返回 405Method Not Allowed符合 Streamable HTTP 仅允许 POST 的语义。默认监听PORT未设置时为 5000可用于远程部署场景如云端 Agent 平台。九、纵深实现频道视频列表的分页会话机制CLAUDE.md 只提及ChannelService负责频道信息与视频列表但仓库源码中隐藏着一个值得单独剖析的实现listManager.ts 为频道视频列表提供了有状态的分页会话机制。核心设计如下会话创建channels_listVideos调用时先通过channels.list拿到频道的 uploads 播放列表 ID 与总视频数再调用ListManager.createSession()生成listId格式为list_ 8 字节随机十六进制并缓存maxResults、sortOrder、totalPages等元信息Token 缓存会话内部用Mapnumber, string记录页码 → nextPageToken首次调用pageTokens new Map([[1, ]])第一页无 token跳页导航channels_navigateList只需携带listId与目标页码。若目标页 token 未缓存calculatePageToken()会逐页翻越前序页面补齐 token 并缓存见 channel.ts会话过期会话超时时间为 30 分钟getSession()检查时发现过期即删除单例构造器还每 10 分钟执行一次cleanupExpiredSessions()清理过期会话避免内存泄漏排序策略sortVideos()支持newest上传列表默认顺序、oldest反转、popular按 viewCount 降序三种排序。这一机制让 LLM 可以在一次对话中创建列表会话 → 翻页 → 跳页而无需重复请求整页数据是值得参考的 MCP 有状态工具设计模式。十、关键依赖与部署使用CLAUDE.md 列出了四大核心依赖在 package.json 中均可确认依赖版本仓库内用途modelcontextprotocol/sdk^1.1.1MCP 协议实现Server、stdio/Streamable HTTP transportgoogleapis^129.0.0YouTube Data API v3 客户端youtube-transcript1.0.6字幕抓取无需 API Keyytdl-core^4.11.5YouTube 视频信息抓取部署与客户端接入方式以 README.md 为准主要包括Claude Desktop 全局安装npm install -g zubeid-youtube-mcp-server再在claude_desktop_config.json的mcpServers中配置command与YOUTUBE_API_KEYnpx 免安装模式command: npx, args: [-y, zubeid-youtube-mcp-server]VS Code 集成在 User Settings (JSON) 或工作区.vscode/mcp.json中声明mcp.servers.youtube支持用${input:apiKey}交互式注入密钥容器化部署目录内提供 Dockerfile可通过环境变量注入YOUTUBE_API_KEY后以 HTTP 模式对外提供服务。十一、开发注意事项小结基于以上源码分析在仓库中进行二次开发时有几点需要留意先构建再启动npm start依赖dist/产物日常迭代请使用npm run dev获得自动重建重启体验新增工具必须双注册在 server.ts 中既要向ListToolsRequestSchema的tools数组添加工具声明含 JSON Schema 入参定义也要在CallToolRequestSchema的switch分支中补充调用逻辑缺一不可新增服务遵循既定模式复制VideoService的懒加载initialize()与 try/catch 错误包装结构并复用removeThumbnails、createErrorMessage工具函数保持代码风格一致参数类型集中管理所有工具入参的 TypeScript 接口统一维护在 types.ts避免在服务间散落重复定义functions/目录不进主构建需要独立分发的附加功能应放在该目录并自行管理构建流程tsconfig 的exclude已将其排除。综上本仓库中的 YouTube MCP Server 以懒加载服务 双入口stdio/HTTP 统一工具注册的工程范式为 AI 语言模型提供了视频查询、字幕抓取、频道管理与播放列表检索的标准化能力。开发者既可以基于npm run dev快速迭代也可以对照server.ts的注册模式扩展属于自己的新工具。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
