YouTube을 AI 에이전트를 위한 리서치 엔진으로 바꿔드립니다. API 키가 필요 없는 MCP 서버와 스킬 팩으로, Claude Code, Codex, OpenCode가 YouTube를 데이터베이스처럼 검색하고, 대규모로 트랜스크립트를 읽고, 영상에서 증거(주장, 수치, 수요 신호)를 채굴할 수 있게 합니다. 막연한 느낌이 아니라 실제 데이터를 기반으로요.
아이디어 엔진 도구는 Reddit과 포럼을 훑습니다. YouTube는 창업자들이 증거를 보여주는 곳입니다 — 수익 대시보드, 플레이북, 카메라 앞에서 말하는 실제 수치 — 그리고 그걸 채굴하는 도구는 없었습니다. TubeScout이 그 역할을 합니다.
Claude Code
claude mcp add --scope user tubescout -- npx -y tubescoutCodex
codex mcp add tubescout -- npx -y tubescoutOpenCode — ~/.config/opencode/opencode.json의 "mcp" 아래에 추가:
"tubescout": { "type": "local", "command": ["npx", "-y", "tubescout"], "enabled": true }이것으로 끝입니다 — API 키도, 설정도 필요 없습니다. 그런 다음 에이전트에게 이렇게 물어보세요:
"지난 달 n8n에 관한 가장 많이 본 영상 5개를 찾아서 사람들이 무엇에 어려움을 겪고 있는지 요약해줘."
가장 쉬운 올인원 (Claude Code): 플러그인으로 설치 — MCP 서버 + 6개 스킬 전부를 두 개의 명령어로:
/plugin marketplace add not0lucky/tubescout
/plugin install tubescout@tubescout또는 스킬 팩을 수동으로 설치 (Claude Code, Codex, OpenCode 모두 지원):
git clone https://github.com/not0lucky/tubescout && cd tubescout
./scripts/install-skills.sh # installs into ~/.claude/skills, ~/.codex/skills, ~/.config/opencode/skillsRelated MCP server: youtube-mcp
도구 | 기능 |
| 필터로 검색 (업로드 기간, 길이, 조회수/날짜 정렬) |
| 전체 메타데이터 + 참여도 ( |
| 3단계 폴백 체인으로 안정적으로 가져오는 일반 텍스트 트랜스크립트 |
| 일괄 트랜스크립트 (최대 10개 영상), 영상별 오류 허용 |
| 채널 포지셔닝 + 조회수가 포함된 최근 업로드 |
| YouTube 자동완성 = 키워드 리서치를 위한 실제 검색 수요 |
스킬 | 용도 |
| 회의론자의 영상 분석: 모든 주장과 수치 추출, 인센티브, 생존자 편향, 검증 가능성 스트레스 테스트 |
| 니치에서 제품 아이디어 채굴 — 수요 신호 + 실제 빌더가 카메라 앞에서 말하는 고충 기반 |
| Go/No-Go 판정: 수요, 포화도, 경쟁사 수치가 실제로 보여주는 것 |
| 채널 전략 읽기: 업로드 주기, 이상치, 성과가 좋은 것 vs 게시하는 것 |
| 튜토리얼을 실행 가능한 단계로 변환 — 정확한 명령어, 설정, 그리고 지나가는 말로 언급된 함정까지 — 내 스택에 맞게 조정 |
| 수요-공급 격차 찾기: 많이 검색되는 주제인데 약하거나, 오래되었거나, 맞지 않는 영상으로 서비스되는 경우 — 콘텐츠 계획이나 제품 각도용 |
모든 스킬은 컨텍스트 인식형입니다: 대화에서 무엇을 만들고 있는지, 스택, 이미 분석한 영상을 읽고, 일반적인 조언 대신 실제 레버리지에 맞춘 판정을 제공합니다.
세 개의 "월 X달러 버는 방법" 영상에 대한 실제 /yt-breakdown 실행 결과를 확인하세요 — 회의론자 검증을 통과한 것과 통과하지 못한 것이 무엇인지 포함해서요.
여기에는 마법이 없습니다. 그리고 그게 핵심입니다:
youtubei.js는 YouTube의 내부 InnerTube API와 통신합니다 — 사이트가 사용하는 것과 동일한 API입니다. 키도, 할당량도 없습니다.
트랜스크립트는 YouTube 자체 자막이며, 폴백 체인으로 가져옵니다: ANDROID 클라이언트 timedtext 트랙 → InnerTube 트랜스크립트 엔드포인트 (간헐적으로 400 오류 발생 — 백오프로 재시도) → 로컬에 yt-dlp가 있으면 사용. 각 응답은 어떤 source가 제공했는지 알려줍니다.
모든 분석은 당신의 에이전트에서 이루어집니다. 서버는 데이터를 제공하고, 스킬은 방법을 제공합니다.
로컬에서 실행하세요. YouTube는 데이터센터 IP를 적극적으로 속도 제한합니다 — 이 서버는 설계상 호스팅 서비스가 아닌 로컬 stdio 서버입니다.
YouTube는 예고 없이 내부를 변경합니다; 문제가 생기면 업데이트하고 (npx는 항상 최신 버전을 가져옴) 실패한 영상 ID와 함께 이슈를 등록하세요.
자막이 비활성화된 영상은 트랜스크립트를 만들 수 없습니다 (드묾; 오류 메시지에 명시적으로 표시됨).
자막 스크래핑은 YouTube ToS의 회색 지대에 있습니다 — 로컬 리서치 도구로는 괜찮지만, 호스팅 유료 제품을 만들지 마세요.
npm install && npm run build
npm test # unit tests (offline)
npm run test:live # live smoke tests against real videos — run before publishing
npm run inspect # MCP Inspector against the built serverMIT — LICENSE 참조.
Anir 제작 — 저는 자동화를 합니다. 더 많은 정보는 agramprojects.com에서.
Channel metadata (name, subscribers, description) plus its recent uploads with views — enough to read a channel's strategy, cadence, and what performs.
| Name | Required | Description | Default |
|---|---|---|---|
| channel | Yes | Channel ID (UC…), @handle, or channel URL | |
| maxVideos | No | How many recent videos to return (default 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries behavioral disclosure. It conveys a read-style operation through words like 'metadata' and 'read a channel's strategy', and it lists the returned content. It does not address ordering, pagination, error behavior, or whether missing channels are handled gracefully, but for a read-only channel-scan tool the gaps are moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that packs the output contents and the intended analytic value without filler. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does the work of explaining return values, and it names the major components: channel metadata and recent uploads with views. It omits precise object shape and ordering, but the schema covers maxVideos limits and the tool's purpose is complete enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters thoroughly: 'channel' accepts ID/@handle/URL and 'maxVideos' has a range and default. The description adds only the general concept of 'recent uploads', so it does not materially enrich the parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (a channel) and the returned data: channel metadata (name, subscribers, description) plus recent uploads with views. It is immediately distinguishable from sibling tools like get_video, search_videos, or transcript tools because it is channel-scoped and returns channel-level analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case: reading a channel's strategy, cadence, and performance. However, it does not explicitly state when to use this tool over siblings, nor does it mention exclusions or when another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
YouTube's autocomplete for a seed term — a direct read on real search demand. Use for keyword research: seed a niche term, get what people actually type. Chain suggestions of suggestions to map a topic space.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Seed term, e.g. 'stamp identifier' or 'n8n' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It clearly states this is a 'direct read' on live YouTube search demand, implying no side effects, and describes the iterative chaining behavior. It does not cover rate limits or error cases, but for a simple read-only autocomplete tool, the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences each carry distinct value: definition, primary use case, and an advanced chaining pattern. The most identifying trait, 'YouTube's autocomplete', is front-loaded. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description conveys enough for an agent to invoke it correctly: the input is a seed term and the result is what users actually type. It could be more explicit about the return format or any authentication/network expectations, but those are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter is already documented with a description and examples. The tool description adds keyword-research context but no new syntax, formatting, or constraints beyond the schema. This matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific verb and resource: 'YouTube's autocomplete for a seed term'. This clearly differentiates it from siblings like search_videos or get_transcript, since autocomplete suggestions are a distinct data product. The phrasing 'direct read on real search demand' reinforces the exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent when to use the tool: for keyword research, seed a niche term, and chain suggestions to map a topic space. It does not mention when not to use it or name specific sibling alternatives, but the given context is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a video's transcript as clean plain text. Resilient: tries InnerTube, then the timedtext caption track, then local yt-dlp if installed. Long transcripts are chunked — check totalChars and call again with offsetChars to continue.
| Name | Required | Description | Default |
|---|---|---|---|
| video | Yes | Video ID or any YouTube URL | |
| language | No | Preferred caption language code (default 'en') | |
| maxChars | No | Chunk size (default 60000) | |
| offsetChars | No | Character offset to resume a chunked transcript |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly reveals the resilience strategy ('tries InnerTube, then the timedtext caption track, then local yt-dlp') and the chunking behavior ('check totalChars and call again with offsetChars'). It does not cover failure modes or exact output structure, but the most important behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: core purpose, resilience strategy, and pagination behavior. The most important information is front-loaded, and there is no filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description sufficiently outlines the chunking contract and fallback approach, allowing an agent to invoke the tool and continue pagination. It falls short of fully describing the return payload shape and does not reference sibling 'get_transcripts', but overall the essential calling context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter already has a description. The tool description adds a little value by connecting offsetChars to the chunking workflow and introducing totalChars as a response field, but it does not substantially enrich parameter understanding beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Fetch a video's transcript as clean plain text', giving a specific verb, resource, and output format. It clearly identifies the tool's core function, but it does not explicitly distinguish itself from the sibling 'get_transcripts', leaving some ambiguity about whether that sibling should be used for different transcript-related needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description explains the fallback chain for fetching but does not mention sibling tools like 'get_transcripts' or state conditions under which this tool is preferred. The agent is left to infer usage from the tool name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Batch transcript fetch (max 10 videos, 3 at a time). Per-video failures don't kill the batch — failed entries carry an error field. Each transcript is truncated to fit; use get_transcript with offsetChars for full text of long ones.
| Name | Required | Description | Default |
|---|---|---|---|
| videos | Yes | Video IDs or URLs | |
| language | No | Preferred caption language code (default 'en') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so excellently. It discloses the batch size, concurrency limit, partial-failure behavior (failed entries carry an error field), and truncation behavior. This gives the agent a reliable model of what the tool will do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with no filler. The core batch behavior is front-loaded, and each clause adds useful operational or fallback information. It is exemplary in economy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately tells the agent what to expect: success, per-item errors, and truncation. It also points to get_transcript for the full-text use case, covering the main follow-up path. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add meaningful new meaning to the 'videos' or 'language' parameters beyond what the schema already provides; it merely repeats the max-item constraint. It earns the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Batch transcript fetch') and resource ('transcripts for multiple videos'), and explicitly contrasts with the singular get_transcript tool. It also conveys key constraints (max 10 videos, 3 at a time) that distinguish it as a batch operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when fetching multiple transcripts in a batch. It also names get_transcript as the alternative for full text of long transcripts, giving the agent a clear routing condition. It does not explicitly state exclusions or compare with other sibling tools, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full metadata + engagement for one video: title, channel, publish date, views, likes, likesPer1kViews (resonance signal, typical range 10-50), category, keywords, description, hasCaptions.
| Name | Required | Description | Default |
|---|---|---|---|
| video | Yes | Video ID or any YouTube URL (watch, youtu.be, shorts) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It is transparent about the returned data and even interprets likesPer1kViews as a resonance signal with a typical range. However, it does not mention error cases, missing fields, authorization, or rate limits — gaps that matter for a tool with no annotation safety signals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one front-loaded sentence: it leads with the tool's purpose, then provides a compact field list and an interpretive note on the resonance signal. Every element earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description is largely complete: it names all return fields and even explains the meaning of a computed metric. It could be fuller by noting behavior when data is missing (e.g., no captions, unavailable likes), but the current level is solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the single parameter at 100% coverage ('Video ID or any YouTube URL'), so the description adds no additional parameter-level meaning. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Full metadata + engagement for one video' and enumerates the exact fields returned. This clearly distinguishes it from sibling tools like search_videos or get_transcript, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is the tool for a single video's full metadata and engagement, not for searching, channel listing, or transcripts. It does not explicitly name alternatives or exclusions, but the one-video scope plus field list makes the intended use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search YouTube for videos (no API key). Returns id, title, channel, published, views, duration, snippet per hit. Use filters to narrow: uploadDate for recency, sortBy view_count to find what performs.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| sortBy | No | Result ordering (default relevance) | |
| duration | No | short <4min, medium 4-20min, long >20min | |
| maxResults | No | Max hits to return (default 15) | |
| uploadDate | No | Only videos uploaded within this window |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and discloses meaningful traits: 'no API key' signals authentication requirements, and the explicit 'Returns id, title, channel, published, views, duration, snippet per hit' describes the response shape. It does not mention rate limits, pagination, or error behavior, but the disclosed return fields and filter effects are substantial for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: action and authentication, return shape, then filter guidance. Front-loaded with the core verb and resource. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter search tool with no output schema and no annotations, the description is fairly complete: purpose, auth trait, per-hit return fields, and filter guidance. It does not explicitly describe the overall response container (e.g., array vs. object) or pagination, but the field list and parameter schema fill most gaps an agent would need to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by mapping two parameters to concrete use cases ('uploadDate for recency, sortBy view_count to find what performs'), adding semantic meaning to the enum choices. It does not describe maxResults or duration, but those are already clear from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search YouTube for videos') and immediately differentiates from sibling tools by the action of searching. The added '(no API key)' and field-list detail confirm it is the general search tool, not get_video or get_channel_videos. Even without naming siblings, the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for when to use filters ('uploadDate for recency, sortBy view_count to find what performs'), which is actionable usage guidance. It does not explicitly contrast with sibling tools or state when not to use this tool, but the search-vs-single-item distinction is strongly implied by the title and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1get_channel_videosget_search_suggestionsget_transcriptget_transcriptsget_videosearch_videosScored across 6 tools
Each tool serves a clearly distinct purpose: search, video metadata, single transcript, batch transcript, channel details, and search suggestions. There is no functional overlap that would confuse an agent.
All tools follow a consistent action_noun pattern (search_videos, get_video, get_transcript, get_transcripts, get_channel_videos, get_search_suggestions). The pluralization for batch operations is intuitive and predictable.
Six tools is a well-scoped size for a YouTube research server. Each tool adds a distinct capability without redundancy or bloat.
The surface covers the core YouTube research workflow: search, video details, transcripts, channel overview, and keyword discovery. Minor gaps like full channel video listing or comments are absent but not critical for the stated purpose.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
YouTube data for AI agents: channels, videos, transcripts, comments, search. Video research.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
YouTube search, whole channels, video stats, comments and full transcripts with timestamps.
