{"_id":"@aaronlin888/youtube-mcp","name":"@aaronlin888/youtube-mcp","dist-tags":{"latest":"0.1.13"},"versions":{"0.1.13":{"name":"@aaronlin888/youtube-mcp","version":"0.1.13","description":"YouTube MCP Server Implementation","type":"module","main":"dist/index.js","module":"./src/index.ts","bin":{"youtube-mcp":"dist/cli.js"},"scripts":{"start":"node ./dist/index.js","build":"tsc","lint":"eslint .","typecheck":"tsc --noEmit","dev":"nodemon --exec \"npm run build && npm start\" --ext ts","prepublishOnly":"npm run build","smithery:build":"npx smithery build","smithery:dev":"npx smithery dev","bump":"node --loader ts-node/esm scripts/release.ts","publish-npm":"npm publish --access public","test":"node --env-file=.env scripts/test.mjs"},"dependencies":{"@modelcontextprotocol/sdk":"^1.1.1","@smithery/sdk":"^1.7.4","dotenv":"^17.3.1","googleapis":"^129.0.0","youtube-transcript":"^1.0.6","ytdl-core":"^4.11.5","zod":"^3.25.46","zod-to-json-schema":"^3.22.5"},"devDependencies":{"@eslint/js":"^9.39.1","@smithery/cli":"^1.4.6","@types/node":"^18.0.0","eslint":"^9.39.1","globals":"^16.5.0","nodemon":"^3.0.0","ts-node":"^10.9.1","typescript":"^5.0.0","typescript-eslint":"^8.47.0"},"keywords":["youtube","mcp","model-context-protocol","ai","claude","anthropic"],"author":{"name":"Aaron Lin"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aaronlin/youtube-mcp.git"},"bugs":{"url":"https://github.com/aaronlin/youtube-mcp/issues"},"homepage":"https://github.com/aaronlin/youtube-mcp#readme","_id":"@aaronlin888/youtube-mcp@0.1.13","gitHead":"9059b41ae34cf465852aec3df1f205694e124628","types":"./dist/index.d.ts","_nodeVersion":"23.10.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-Nobz9X+F03P45Cdw1MOjzbIs9RK2V0PAx52Fl4xFYR5UG7nN2TJhLnlTWcQzNmkaTgRz3LCnXp226nfknEs90Q==","shasum":"999d3727f987f3fc01507b5f5eb6596ee66f37dd","tarball":"https://registry.npmjs.org/@aaronlin888/youtube-mcp/-/youtube-mcp-0.1.13.tgz","fileCount":22,"unpackedSize":47515,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCDjn/USqiN9/TQ3vM7mXTMEtlLvssP0j3YyXNzgc2CoAIgT3IzjRSZOLzBdDEtdRBhKPbaXwhESzlI7JBxdxl1K/c="}]},"_npmUser":{"name":"aaronlin888","email":"vagante@gmail.com"},"directories":{},"maintainers":[{"name":"aaronlin888","email":"vagante@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/youtube-mcp_0.1.13_1773645134752_0.09471651031992079"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-16T07:12:14.688Z","0.1.13":"2026-03-16T07:12:14.914Z","modified":"2026-03-16T07:12:15.089Z"},"maintainers":[{"name":"aaronlin888","email":"vagante@gmail.com"}],"description":"YouTube MCP Server Implementation","homepage":"https://github.com/aaronlin/youtube-mcp#readme","keywords":["youtube","mcp","model-context-protocol","ai","claude","anthropic"],"repository":{"type":"git","url":"git+https://github.com/aaronlin/youtube-mcp.git"},"author":{"name":"Aaron Lin"},"bugs":{"url":"https://github.com/aaronlin/youtube-mcp/issues"},"license":"MIT","readme":"# YouTube MCP Server\n\n[![smithery badge](https://smithery.ai/badge/@aaronlin888/youtube-mcp)](https://smithery.ai/server/@aaronlin888/youtube-mcp)\n\nA Model Context Protocol (MCP) server implementation for YouTube, enabling AI language models to interact with YouTube content through a standardized interface. Optimized for **90% Smithery quality score** with comprehensive resources, prompts, and flexible configuration.\n\n## Features\n\n### Video Information\n\n* Get video details (title, description, duration, etc.) **with direct URLs**\n* List channel videos **with direct URLs**\n* Get video statistics (views, likes, comments)\n* Search videos across YouTube **with direct URLs**\n* **NEW**: Enhanced video responses include `url` and `videoId` fields for easy integration\n\n### Transcript Management\n\n* Retrieve video transcripts\n* Support for multiple languages\n* Get timestamped captions\n* Search within transcripts\n\n### Direct Resources & Prompts\n\n* **Resources**:\n  * `youtube://transcript/{videoId}`: Access transcripts directly via resource URIs\n  * `youtube://info`: Server information and usage documentation (Smithery discoverable)\n* **Prompts**:\n  * `summarize-video`: Automated workflow to get and summarize video content\n  * `analyze-channel`: Comprehensive analysis of a channel's content strategy\n* **Annotations**: All tools include capability hints (read-only, idempotent) for better LLM performance\n\n### Channel Management\n\n* Get channel details\n* List channel playlists\n* Get channel statistics\n* Search within channel content\n\n### Playlist Management\n\n* List playlist items\n* Get playlist details\n* Search within playlists\n* Get playlist video transcripts\n\n## Installation\n\n### Quick Setup for Claude Desktop\n\n1. Install the package:\n\n```bash\nnpm install -g @aaronlin888/youtube-mcp\n```\n\n1. Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"youtube-mcp\": {\n      \"command\": \"youtube-mcp\",\n      \"env\": {\n        \"YOUTUBE_API_KEY\": \"your_youtube_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Alternative: Using NPX (No Installation Required)\n\nAdd this to your Claude Desktop configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"youtube\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aaronlin888/youtube-mcp\"],\n      \"env\": {\n        \"YOUTUBE_API_KEY\": \"your_youtube_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Installing via Smithery\n\nTo install YouTube MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@aaronlin888/youtube-mcp):\n\n```bash\nnpx -y @smithery/cli@latest install @aaronlin888/youtube-mcp --client claude\n```\n\n## Configuration\n\nSet the following environment variables:\n\n* `YOUTUBE_API_KEY`: Your YouTube Data API key (required)\n* `YOUTUBE_TRANSCRIPT_LANG`: Default language for transcripts (optional, defaults to 'en')\n\n### Using with VS Code\n\nFor one-click installation, click one of the install buttons below:\n\n[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=youtube&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40sfiorini%2Fyoutube-mcp%22%5D%2C%22env%22%3A%7B%22YOUTUBE_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22YouTube+API+Key%22%2C%22password%22%3Atrue%7D%5D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=youtube&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40sfiorini%2Fyoutube-mcp%22%5D%2C%22env%22%3A%7B%22YOUTUBE_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22YouTube+API+Key%22%2C%22password%22%3Atrue%7D%5D&quality=insiders)\n\n### Manual Installation\n\nIf you prefer manual installation, first check the install buttons at the top of this section. Otherwise, follow these steps:\n\nAdd the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.\n\n```json\n{\n  \"mcp\": {\n    \"inputs\": [\n      {\n        \"type\": \"promptString\",\n        \"id\": \"apiKey\",\n        \"description\": \"YouTube API Key\",\n        \"password\": true\n      }\n    ],\n    \"servers\": {\n      \"youtube\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"@aaronlin888/youtube-mcp\"],\n        \"env\": {\n          \"YOUTUBE_API_KEY\": \"${input:apiKey}\"\n        }\n      }\n    }\n  }\n}\n```\n\nOptionally, you can add it to a file called `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"inputs\": [\n    {\n      \"type\": \"promptString\",\n      \"id\": \"apiKey\",\n      \"description\": \"YouTube API Key\",\n      \"password\": true\n    }\n  ],\n  \"servers\": {\n    \"youtube\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aaronlin888/youtube-mcp\"],\n      \"env\": {\n        \"YOUTUBE_API_KEY\": \"${input:apiKey}\"\n      }\n    }\n  }\n}\n```\n\n## YouTube API Setup\n\n1. Go to Google Cloud Console\n2. Create a new project or select an existing one\n3. Enable the YouTube Data API v3\n4. Create API credentials (API key)\n5. Copy the API key for configuration\n\n## Examples\n\n### Managing Videos\n\n```javascript\n// Get video details (now includes URL)\nconst video = await youtube.videos.getVideo({\n  videoId: \"dQw4w9WgXcQ\"\n});\n\n// Enhanced response now includes:\n// - video.url: \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n// - video.videoId: \"dQw4w9WgXcQ\"\n// - All original YouTube API data\n\n// Get video transcript\nconst transcript = await youtube.transcripts.getTranscript({\n  videoId: \"video-id\",\n  language: \"en\"\n});\n\n// Search videos (results now include URLs)\nconst searchResults = await youtube.videos.searchVideos({\n  query: \"search term\",\n  maxResults: 10\n});\n\n// Each search result includes:\n// - result.url: \"https://www.youtube.com/watch?v={videoId}\"\n// - result.videoId: \"{videoId}\"\n// - All original YouTube search data\n```\n\n### Managing Channels\n\n```javascript\n// Get channel details\nconst channel = await youtube.channels.getChannel({\n  channelId: \"channel-id\"\n});\n\n// List channel videos\nconst videos = await youtube.channels.listVideos({\n  channelId: \"channel-id\",\n  maxResults: 50\n});\n```\n\n### Managing Playlists\n\n```javascript\n// Get playlist items\nconst playlistItems = await youtube.playlists.getPlaylistItems({\n  playlistId: \"playlist-id\",\n  maxResults: 50\n});\n\n// Get playlist details\nconst playlist = await youtube.playlists.getPlaylist({\n  playlistId: \"playlist-id\"\n});\n```\n\n## Enhanced Response Structure\n\n### Video Objects with URLs\n\nAll video-related responses now include enhanced fields for easier integration:\n\n```typescript\ninterface EnhancedVideoResponse {\n  // Original YouTube API fields\n  kind?: string;\n  etag?: string;\n  id?: string | YouTubeSearchResultId;\n  snippet?: YouTubeSnippet;\n  contentDetails?: any;\n  statistics?: any;\n\n  // NEW: Enhanced fields\n  url: string;           // Direct YouTube video URL\n  videoId: string;       // Extracted video ID\n}\n```\n\n### Example Enhanced Response\n\n```json\n{\n  \"kind\": \"youtube#video\",\n  \"id\": \"dQw4w9WgXcQ\",\n  \"snippet\": {\n    \"title\": \"Never Gonna Give You Up\",\n    \"channelTitle\": \"Rick Astley\",\n    \"description\": \"Official video for \\\"Never Gonna Give You Up\\\"\"\n  },\n  \"statistics\": {\n    \"viewCount\": \"1.5B\",\n    \"likeCount\": \"15M\"\n  },\n  // Enhanced fields:\n  \"url\": \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\",\n  \"videoId\": \"dQw4w9WgXcQ\"\n}\n```\n\n### Benefits\n\n* **Easy URL Access**: No need to manually construct URLs\n* **Consistent Structure**: Both search and individual video responses include URLs\n* **Backward Compatible**: All existing YouTube API data is preserved\n* **Type Safe**: Full TypeScript support available\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript to JavaScript\nnpm run build\n\n# Development mode with auto-rebuild and hot reload\nnpm run dev\n\n# Start the server (requires YOUTUBE_API_KEY)\nnpm start\n\n# Publish to npm (runs build first)\nnpm run prepublishOnly\n```\n\n### Architecture\n\nThis project uses a **dual-architecture service-based design** with the following features:\n\n* **Shared Utilities**: Single source of truth for all MCP server configuration (`src/server-utils.ts`)\n* **Modern McpServer**: Updated from deprecated `Server` class to the new `McpServer`\n* **Dynamic Version Management**: Version automatically read from `package.json`\n* **Type-Safe Tool Registration**: Uses `zod` schemas for input validation\n* **ES Modules**: Full ES module support with proper `.js` extensions\n* **Enhanced Video Responses**: All video operations include `url` and `videoId` fields\n* **Lazy Initialization**: YouTube API client initialized only when needed\n* **Code Deduplication**: Eliminated 90% code duplication through shared utilities (407 → 285 lines)\n\n### Project Structure\n\n```diagram\nsrc/\n├── server-utils.ts        # 🆕 Shared MCP server utilities (single source of truth)\n├── index.ts              # Smithery deployment entry point\n├── server.ts             # CLI deployment entry point\n├── services/             # Core business logic\n│   ├── video.ts         # Video operations (search, getVideo)\n│   ├── transcript.ts    # Transcript retrieval\n│   ├── playlist.ts      # Playlist operations\n│   └── channel.ts       # Channel operations\n├── types.ts             # TypeScript interfaces\n└── cli.ts               # CLI wrapper for standalone execution\n```\n\n### Key Features\n\n* **Smithery Optimized**: Achieved 90%+ Smithery quality score with comprehensive resources, prompts, and configuration\n* **Shared Utilities Architecture**: Eliminated 90% code duplication with single source of truth\n* **Enhanced Video Responses**: All video objects include direct YouTube URLs\n* **Flexible Configuration**: Optional config via Smithery UI or environment variables\n* **Type-Safe Development**: Full TypeScript support with `zod` validation\n* **Modern MCP Tools**: Uses `registerTool` instead of manual request handlers\n* **Comprehensive Resources**: Discoverable resources and prompts for better LLM integration\n* **Error Handling**: Comprehensive error handling with descriptive messages\n\n## Contributing\n\nSee CONTRIBUTING.md for information about contributing to this repository.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","readmeFilename":"README.md","_rev":"1-3439f1ae8fafad63c67c01925ea63a71"}