{
  "markdown": "# YouTube Research MCP\n\n[![CI](https://github.com/coyaSONG/youtube-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/coyaSONG/youtube-mcp-server/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/%40coyasong%2Fyoutube-mcp-server?logo=npm)](https://www.npmjs.com/package/@coyasong/youtube-mcp-server)\n[![npm downloads](https://img.shields.io/npm/dm/%40coyasong%2Fyoutube-mcp-server?logo=npm)](https://www.npmjs.com/package/@coyasong/youtube-mcp-server)\n[![GitHub stars](https://img.shields.io/github/stars/coyaSONG/youtube-mcp-server?style=flat&logo=github)](https://github.com/coyaSONG/youtube-mcp-server/stargazers)\n[![Smithery](https://smithery.ai/badge/coyaSONG/youtube-mcp-server)](https://smithery.ai/servers/coyaSONG/youtube-mcp-server)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nTurn YouTube videos into citation-ready research for Codex, Claude, Cursor, and other MCP clients. Paste a video URL and get transcript evidence with timestamps and links that open at the exact quoted moment.\n\n![YouTube Research MCP turns a video URL into focused timestamp-linked evidence](https://raw.githubusercontent.com/coyaSONG/youtube-mcp-server/main/docs/demo.svg)\n\n```text\nInput:  https://youtu.be/dQw4w9WgXcQ\nOutput: [01:05] ...evidence text...\n        https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=65s\n```\n\nNo YouTube API key is required for transcript research.\n\n## Why this server\n\n- **Citation-ready research** — every transcript segment includes a timestamp and source URL.\n- **Zero-key quick start** — transcripts work immediately; add an API key only for search and analytics.\n- **URL-first input** — accepts normal, short, Shorts, embed, live, and raw video-ID formats.\n- **Agent-efficient filtering** — search inside transcripts and return nearby context instead of spending tokens on the entire video.\n- **Full YouTube intelligence** — optional API mode adds comments, video/channel statistics, trends, and comparisons.\n- **Remote-native MCP** — Streamable HTTP transport at `/mcp`, plus Docker and Smithery support.\n\n## Architecture and trust boundary\n\n```mermaid\nflowchart LR\n    C[MCP client] -->|stdio or Streamable HTTP| T[Transport]\n    T --> R[Tool and resource registry]\n    R --> S[YouTubeService]\n    S --> K[(In-memory cache)]\n    S -->|no key required| YT[Caption tracks]\n    S -->|optional API key| API[YouTube Data API v3]\n```\n\nThe MCP layer validates inputs and returns structured evidence; it does not ask a model to invent summaries or citations. Transcript tools derive timestamps and canonical links from caption segments. Data API tools return an explicit key-required error when `YOUTUBE_API_KEY` is unavailable, and remote authentication is enforced before MCP session handling.\n\n## Focused evidence, not a transcript dump\n\nThe included live smoke test asks a focused question about a public video and compares the response with the full timestamped transcript:\n\n| Response | Characters returned |\n|---|---:|\n| Full transcript | 85,518 |\n| `research-video` (3 citations with source identity) | 1,550 |\n| Reduction | **98.2%** |\n\nThis measures response characters, not model-specific tokens. Reproduce it against the default public fixture—or substitute your own video and query:\n\n```bash\nnpm run test:live\nLIVE_TEST_VIDEO='https://youtu.be/VIDEO_ID' LIVE_TEST_QUERY='evaluation' npm run test:live\n```\n\n## Quick start — no API key\n\nRequirements: Node.js 20 or newer.\n\nThe shortest local install uses stdio and needs no API key:\n\n```bash\ncodex mcp add youtube-research -- npx -y @coyasong/youtube-mcp-server@latest\n```\n\nFor Claude Desktop and other MCPB-compatible desktop clients, download the\n[latest one-click MCP bundle](https://github.com/coyaSONG/youtube-mcp-server/releases/latest/download/youtube-research-mcp.mcpb)\nand open it. The bundle vendors its runtime dependencies, starts locally over\nstdio, and asks for a YouTube API key only if you want the optional analytics\ntools.\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=youtube-research&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40coyasong%2Fyoutube-mcp-server%40latest%22%5D%7D)\n\nOr install from the VS Code command line:\n\n```bash\ncode --add-mcp '{\"name\":\"youtube-research\",\"command\":\"npx\",\"args\":[\"-y\",\"@coyasong/youtube-mcp-server@latest\"]}'\n```\n\nFor Claude Desktop, Cursor, and other stdio clients, use command `npx` with arguments `-y @coyasong/youtube-mcp-server@latest`.\n\nTo run the Streamable HTTP transport instead:\n\n```bash\ngit clone https://github.com/coyaSONG/youtube-mcp-server.git\ncd youtube-mcp-server\nnpm install\nnpm run build\nnpm start\n```\n\nThe server starts at `http://localhost:3000/mcp` in `transcript-only` mode. Confirm it with:\n\n```bash\ncurl http://localhost:3000/health\n```\n\n### Connect from Codex\n\nWith the HTTP server running:\n\n```bash\ncodex mcp add youtube-research --url http://localhost:3000/mcp\n```\n\nThen ask Codex:\n\n```text\nUse research-video to find what this video says about evaluation,\nand cite the exact moments: https://www.youtube.com/watch?v=VIDEO_ID\n```\n\n### Connect with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector\n# Connect to http://localhost:3000/mcp\n```\n\n### Install through Smithery\n\n```bash\nnpx -y smithery@latest auth login\nnpx -y smithery@latest mcp add coyaSONG/youtube-mcp-server --client claude\n```\n\n## Enable search, comments, and analytics\n\nSet a YouTube Data API v3 key to switch from `transcript-only` to `full` mode:\n\n```bash\nexport YOUTUBE_API_KEY=your_key_here\nnpm start\n```\n\n`YOUTUBE_API_KEY` is optional. `PORT` defaults to `3000`.\n\n## Secure a remote deployment\n\nDo not expose a full-mode server publicly without authentication: unauthenticated users could consume your YouTube API quota. Set a strong bearer token and restrict browser origins when deploying outside localhost:\n\n```bash\nexport MCP_BEARER_TOKEN='replace-with-a-long-random-secret'\nexport CORS_ORIGIN='https://your-client.example'\nexport MAX_SESSIONS=100\nexport SESSION_IDLE_TIMEOUT_MS=1800000\nnpm start\n```\n\nBrowser origins are denied by default. `CORS_ORIGIN` accepts a comma-separated\nallowlist of exact `http://` or `https://` origins; wildcard origins are rejected.\n\nConnect Codex using an environment variable rather than writing the secret into its configuration:\n\n```bash\nexport YOUTUBE_MCP_TOKEN='replace-with-a-long-random-secret'\ncodex mcp add youtube-research \\\n  --url https://your-server.example/mcp \\\n  --bearer-token-env-var YOUTUBE_MCP_TOKEN\n```\n\n`/health` remains public for container health checks. MCP requests return `401` when authentication is enabled and the bearer token is missing or invalid. Idle sessions are removed automatically, and `MAX_SESSIONS` bounds memory use.\n\n## Best first tool\n\n`research-video` accepts:\n\n- `video`: a YouTube URL or 11-character video ID\n- `language`: optional caption language such as `en`, `ko`, or `ja`\n- `query`: optional phrase to find inside the transcript\n- `contextLines`: surrounding segments to retain, from 0 to 5\n- `matchMode`: `word` (default) or `substring`\n- `startSeconds` / `endSeconds`: optional time window\n- `offset`: result offset for pagination\n- `maxSegments`: response cap from 1 to 1,000 (default: 200)\n\nIt returns structured JSON containing the video title and channel identity, canonical video URL, full caption-track duration and segment count, matching transcript segments, human-readable citation labels, timestamps, directly navigable citation URLs, and pagination metadata. For long videos, use a `query` or time window first; follow `nextOffset` only when more evidence is needed.\n\n### Compare evidence across videos\n\n`research-videos` applies one focused query to 2–5 video URLs concurrently. It returns the same structured, timestamp-linked evidence for each source while capping results per video. This is useful for comparing interviews, checking whether multiple sources support a claim, or researching a topic across a short watchlist.\n\n```json\n{\n  \"videos\": [\n    \"https://youtu.be/VIDEO_ONE\",\n    \"https://youtu.be/VIDEO_TWO\"\n  ],\n  \"query\": \"evaluation\",\n  \"maxSegmentsPerVideo\": 10\n}\n```\n\nSee [YouTube Research Recipes](docs/recipes.md) for copy-paste workflows for\nfact-checking claims, comparing interviews, navigating long talks, researching\nmultilingual captions, and building citation-ready notes.\n\n## Capability modes\n\n| Capability | No-key mode | With `YOUTUBE_API_KEY` |\n|---|:---:|:---:|\n| Transcript research, filtering, key moments, segmentation, summaries | Yes | Yes |\n| Video search and comments | No | Yes |\n| Video/channel metadata, statistics, trends, and comparisons | No | Yes |\n\nCaptions must be available for the requested video. Age-restricted, private, region-restricted, or caption-disabled videos may not return a transcript.\n\nIf this project saves you research time, consider\n[starring the repository](https://github.com/coyaSONG/youtube-mcp-server) so\nother agent builders can discover it.\n\nSee the broader [AI tooling portfolio](https://coyasong.dev/portfolio) for the\nreliability principles shared with `ralph-research` and `tmuxicate`.\n\n## Docker\n\n```bash\ndocker build -t youtube-research-mcp .\ndocker run --rm -p 3000:3000 youtube-research-mcp\n\n# Full mode\ndocker run --rm -p 3000:3000 -e YOUTUBE_API_KEY=your_key youtube-research-mcp\n```\n\n## Development\n\n```bash\nnpm run dev             # HTTP server from TypeScript\nnpm test                # build and run all tests\nnpm run test:live       # live public-video transcript and citation smoke test\nnpm run test:user       # clean-room smoke test against the published npm package\nnpm run test:mcpb       # build, unpack, and exercise the installable MCP bundle\n```\n\nMaintainers can follow the [release guide](docs/releasing.md). Published GitHub\nreleases run the complete npm, MCP Registry, MCPB, and Smithery delivery pipeline.\n\n## API Reference\n\n### Resources\n\n- `youtube://video/{videoId}` - Get detailed information about a specific video\n- `youtube://channel/{channelId}` - Get information about a specific channel\n- `youtube://transcript/{videoId}` - Get transcript for a specific video\n  - Optional query parameter: `?language=LANGUAGE_CODE` (e.g., `en`, `ko`, `ja`)\n\n### Tools\n\n#### Basic Tools\n- `research-video` - Get citation-ready transcript evidence from a URL or video ID without an API key\n- `research-videos` - Compare timestamp-linked evidence across 2–5 videos without an API key\n- `search-videos` - Search for YouTube videos with advanced filtering options\n- `get-video-comments` - Get comments for a specific video\n- `get-video-transcript` - Get transcript for a specific video with optional language\n- `enhanced-transcript` - Advanced transcript extraction with filtering, search, and multi-video capabilities\n- `get-key-moments` - Extract key moments with timestamps from a video transcript for easier navigation\n- `get-segmented-transcript` - Divide a video transcript into segments for easier analysis\n\nTools requiring `YOUTUBE_API_KEY` are search, comments, statistics, discovery, and channel analysis. `enhanced-transcript` needs the key only when `includeMetadata` is `true`.\n\n#### Statistical Tools\n- `get-video-stats` - Get statistical information for a specific video\n- `get-channel-stats` - Get subscriber count, view count, and other channel statistics\n- `compare-videos` - Compare statistics across multiple videos\n\n#### Discovery Tools\n- `get-trending-videos` - Retrieve trending videos by region and category\n- `get-video-categories` - Get available video categories for a specific region\n\n#### Analysis Tools\n- `analyze-channel-videos` - Analyze performance trends of videos from a specific channel\n\n### Prompts\n\n- `video-analysis` - Generate an analysis of a YouTube video\n- `transcript-summary` - Generate a summary of a video based on its transcript with customizable length and keywords extraction\n- `segment-by-segment-analysis` - Provide detailed breakdown of content by analyzing each segment of the video\n\n## Examples\n\n### Accessing a Video Transcript\n\n```\nyoutube://transcript/dQw4w9WgXcQ\n```\n\n### Getting a Transcript in a Specific Language\n\n```\nyoutube://transcript/dQw4w9WgXcQ?language=en\n```\n\n### Using the Statistical Tools\n\n```javascript\n// Get video statistics\n{\n  \"type\": \"tool\",\n  \"name\": \"get-video-stats\",\n  \"parameters\": {\n    \"videoId\": \"dQw4w9WgXcQ\"\n  }\n}\n\n// Compare multiple videos\n{\n  \"type\": \"tool\",\n  \"name\": \"compare-videos\",\n  \"parameters\": {\n    \"videoIds\": [\"dQw4w9WgXcQ\", \"9bZkp7q19f0\"]\n  }\n}\n```\n\n### Using the Transcript Summary Prompt\n\n```javascript\n{\n  \"type\": \"prompt\",\n  \"name\": \"transcript-summary\",\n  \"parameters\": {\n    \"videoId\": \"dQw4w9WgXcQ\",\n    \"language\": \"en\"\n  }\n}\n```\n\n### Using the Enhanced Transcript Tool\n\n```javascript\n// Basic multi-video transcript extraction\n{\n  \"type\": \"tool\",\n  \"name\": \"enhanced-transcript\",\n  \"parameters\": {\n    \"videoIds\": [\"dQw4w9WgXcQ\", \"9bZkp7q19f0\"],\n    \"format\": \"timestamped\"\n  }\n}\n\n// With search and time filtering\n{\n  \"type\": \"tool\",\n  \"name\": \"enhanced-transcript\",\n  \"parameters\": {\n    \"videoIds\": [\"dQw4w9WgXcQ\"],\n    \"filters\": {\n      \"timeRange\": {\n        \"start\": 60,  // Start at 60 seconds\n        \"end\": 180    // End at 180 seconds\n      },\n      \"search\": {\n        \"query\": \"never gonna\",\n        \"contextLines\": 2\n      }\n    },\n    \"format\": \"merged\"\n  }\n}\n\n// With duration-based segmentation for easier analysis\n{\n  \"type\": \"tool\",\n  \"name\": \"enhanced-transcript\",\n  \"parameters\": {\n    \"videoIds\": [\"dQw4w9WgXcQ\"],\n    \"filters\": {\n      \"segment\": {\n        \"count\": 5,\n        \"method\": \"smart\"  // Balances caption duration across segments\n      }\n    },\n    \"format\": \"timestamped\",\n    \"language\": \"en\"\n  }\n}\n```\n\n### Using the Enhanced Transcript Analysis Features\n\n```javascript\n// Get key moments from a video\n{\n  \"type\": \"tool\",\n  \"name\": \"get-key-moments\",\n  \"parameters\": {\n    \"videoId\": \"dQw4w9WgXcQ\",\n    \"maxMoments\": 5\n  }\n}\n\n// Get a segmented transcript\n{\n  \"type\": \"tool\",\n  \"name\": \"get-segmented-transcript\",\n  \"parameters\": {\n    \"videoId\": \"dQw4w9WgXcQ\",\n    \"segmentCount\": 4\n  }\n}\n\n// Get a segment-by-segment analysis\n{\n  \"type\": \"prompt\",\n  \"name\": \"segment-by-segment-analysis\",\n  \"parameters\": {\n    \"videoId\": \"dQw4w9WgXcQ\",\n    \"segmentCount\": 4\n  }\n}\n\n// Get customized transcript summary\n{\n  \"type\": \"prompt\",\n  \"name\": \"transcript-summary\",\n  \"parameters\": {\n    \"videoId\": \"dQw4w9WgXcQ\",\n    \"language\": \"en\",\n    \"summaryLength\": \"detailed\",\n    \"includeKeywords\": true\n  }\n}\n```\n\n## Error Handling\n\nThe server handles various error conditions, including:\n\n- Invalid or missing API key for Data API tools\n- Video or channel not found\n- Transcript not available\n- Network issues\n\n## License\n\nMIT\n\n## Acknowledgements\n\n- [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- [YouTube Data API](https://developers.google.com/youtube/v3)\n- [YouTube.js](https://github.com/LuanRT/YouTube.js)\n",
  "bytes": 15066,
  "sha": "af2429ae482f88f69d3de91641ccdea1a0b43958a370da30c8baaf874db3492e",
  "repo_slug": "coyasong/youtube-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_coyasong_youtube_research_ac618bf9/readme"
}