list_comments
Retrieve top-level comments from a YouTube video, sorted newest first, with comment IDs, authors, text, and like counts.
Instructions
List top-level comment threads on a video (newest first). Returns comment IDs, authors, text, and like counts.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| video_id | Yes | Video ID to list comments from | |
| max_results | No |
Implementation Reference
- src/tools/comments.ts:25-45 (handler)The tool handler function that executes the list_comments logic: calls YouTubeClient.listComments, formats the results into a text response with comment IDs, authors, likes, and reply counts.
server.tool( "list_comments", "List top-level comment threads on a video (newest first). Returns comment IDs, authors, text, and like counts.", listCommentsSchema, async (args) => { const data = await client.listComments(args.video_id, args.max_results); const lines = [ `Found ${data.items.length} comment thread(s) on ${args.video_id}:`, ...data.items.map((thread) => { const top = thread.snippet?.topLevelComment?.snippet; const id = thread.snippet?.topLevelComment?.id ?? "?"; const author = top?.authorDisplayName ?? "?"; const text = (top?.textOriginal ?? "").replace(/\s+/g, " ").slice(0, 160); const likes = top?.likeCount ?? 0; const replies = thread.snippet?.totalReplyCount ?? 0; return ` ${id} — ${author} (${likes}❤, ${replies}↩): ${text}`; }), ]; return { content: [{ type: "text" as const, text: lines.join("\n") }] }; }, ); - src/tools/comments.ts:5-8 (schema)Input schema for list_comments: requires a video_id string and an optional max_results number (1-100, default 20).
const listCommentsSchema = { video_id: z.string().describe("Video ID to list comments from"), max_results: z.number().int().min(1).max(100).default(20), }; - src/server.ts:49-49 (registration)Registration of the comment tools (including list_comments) on the MCP server instance.
registerCommentTools(s, youtube); - src/youtube/client.ts:206-213 (helper)YouTubeClient helper method that calls the YouTube Data API v3 /commentThreads endpoint to fetch top-level comments for a video.
listComments(videoId: string, maxResults = 20): Promise<{ items: CommentThread[] }> { return this.dataGet("/commentThreads", { part: "snippet,replies", videoId, maxResults: String(maxResults), order: "time", }); } - src/youtube/types.ts:58-75 (schema)TypeScript type definition for CommentThread returned by the YouTube API, used as the response type for listComments.
export interface CommentThread { id: string; snippet?: { topLevelComment?: { id: string; snippet: { authorDisplayName: string; authorChannelId?: { value: string }; textDisplay: string; textOriginal: string; likeCount: number; publishedAt: string; updatedAt: string; moderationStatus?: "heldForReview" | "likelySpam" | "published" | "rejected"; }; }; totalReplyCount?: number; };