@alexspalato/youtube-transcript-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alexadark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# YouTube Transcript MCP
+
+Get YouTube video transcripts directly in Claude. Just share a YouTube link - no technical syntax needed.
+
+## What It Does
+
+Share any YouTube URL with Claude, and this MCP lets Claude fetch the transcript for you. Claude will naturally ask how you'd like to view it:
+
+- **Readable text** - Clean paragraphs, perfect for reading and analysis
+- **With timestamps** - Each line shows when it was said (great for referencing specific moments)
+- **Structured data** - JSON format with full metadata (for developers)
+
+Works with any YouTube video that has captions, in any language.
+
+## Installation
+
+**One command:**
+
+```bash
+npm install -g @alexspalato/youtube-transcript-mcp
+```
+
+## Setup
+
+### For Claude Code
+
+```bash
+claude mcp add youtube-transcript
+```
+
+Restart Claude Code and you're done!
+
+### For Claude Desktop
+
+1. Open `~/Library/Application Support/Claude/claude_desktop_config.json`
+2. Add this:
+
+```json
+{
+  "mcpServers": {
+    "youtube-transcript": {
+      "command": "npx",
+      "args": ["-y", "@alexspalato/youtube-transcript-mcp"]
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop
+
+## How to Use
+
+Just chat naturally with Claude:
+
+> "Can you get the transcript from https://youtu.be/dQw4w9WgXcQ?"
+
+> "Summarize this video: https://youtu.be/eT_6uaHNlk8"
+
+> "Get me the transcript with timestamps from this tutorial..."
+
+Claude will handle everything - fetching the transcript, asking about your format preference, and displaying it clearly.
+
+### Multiple Languages
+
+Works with any language that has captions:
+
+> "Get the Spanish transcript from this video"
+
+> "Show me this video's transcript in French"
+
+Common language codes: `en`, `es`, `fr`, `de`, `ja`, `ko`, `zh`, `pt`, `ru`, `ar`, `hi`
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { fetchTranscript } from "youtube-transcript-plus";
+/**
+ * Formats seconds into HH:MM:SS or MM:SS format
+ */
+function formatTimestamp(seconds) {
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const secs = Math.floor(seconds % 60);
+    if (hours > 0) {
+        return `${hours.toString().padStart(2, "0")}:${minutes
+            .toString()
+            .padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+    }
+    return `${minutes.toString().padStart(2, "0")}:${secs
+        .toString()
+        .padStart(2, "0")}`;
+}
+/**
+ * Extracts video ID from YouTube URL or returns the input if it's already an ID
+ */
+function extractVideoId(urlOrId) {
+    // If it's already just an ID (no URL patterns), return it
+    if (!/[/:.]/.test(urlOrId)) {
+        return urlOrId;
+    }
+    // Handle various YouTube URL formats
+    const patterns = [
+        /(?:youtube\.com\/watch\?v=|youtu\.be\/|youtube\.com\/embed\/)([^&\?\/]+)/,
+        /youtube\.com\/shorts\/([^&\?\/]+)/,
+    ];
+    for (const pattern of patterns) {
+        const match = urlOrId.match(pattern);
+        if (match) {
+            return match[1];
+        }
+    }
+    // If no pattern matched, assume it's an ID
+    return urlOrId;
+}
+/**
+ * Formats transcript segments into plain text paragraphs
+ */
+function formatPlainText(segments) {
+    return segments.map((segment) => segment.text.trim()).join(" ");
+}
+/**
+ * Formats transcript segments with timestamps
+ */
+function formatTimestamped(segments) {
+    return segments
+        .map((segment) => {
+        const timestamp = formatTimestamp(segment.offset);
+        return `[${timestamp}] ${segment.text.trim()}`;
+    })
+        .join("\n");
+}
+/**
+ * Formats transcript segments as JSON
+ */
+function formatJson(segments) {
+    const formatted = segments.map((segment) => ({
+        timestamp: formatTimestamp(segment.offset),
+        offset: segment.offset,
+        duration: segment.duration,
+        text: segment.text.trim(),
+    }));
+    return JSON.stringify(formatted, null, 2);
+}
+const server = new Server({
+    name: "youtube-transcript-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "get_transcript",
+                description: "Fetches YouTube video transcripts. When a user shares a YouTube URL, use this tool to retrieve the transcript. If the user doesn't specify a format preference, ask them how they'd like to view it: as readable text (plain), with timestamps for referencing specific moments (timestamped), or as structured data (json).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        url: {
+                            type: "string",
+                            description: "YouTube video URL or video ID",
+                        },
+                        lang: {
+                            type: "string",
+                            description: "Language code for transcript (e.g., 'en', 'es', 'fr'). Defaults to 'en'.",
+                            default: "en",
+                        },
+                        format: {
+                            type: "string",
+                            enum: ["plain", "timestamped", "json"],
+                            description: "Output format: 'plain' for readable text (default), 'timestamped' for text with [00:00] timestamps, 'json' for structured data with metadata",
+                            default: "plain",
+                        },
+                    },
+                    required: ["url"],
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name !== "get_transcript") {
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    }
+    const url = String(request.params.arguments?.url || "");
+    const lang = String(request.params.arguments?.lang || "en");
+    const format = (request.params.arguments?.format || "plain");
+    if (!url) {
+        throw new Error("URL parameter is required");
+    }
+    try {
+        const videoId = extractVideoId(url);
+        const transcript = await fetchTranscript(videoId, { lang });
+        let formattedText;
+        switch (format) {
+            case "timestamped":
+                formattedText = formatTimestamped(transcript);
+                break;
+            case "json":
+                formattedText = formatJson(transcript);
+                break;
+            case "plain":
+            default:
+                formattedText = formatPlainText(transcript);
+                break;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formattedText,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error fetching transcript: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("YouTube Transcript MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@alexspalato/youtube-transcript-mcp",
+  "version": "1.0.0",
+  "description": "Get YouTube transcripts in Claude with natural language - no technical syntax needed",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "youtube-transcript-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "youtube",
+    "transcript",
+    "claude",
+    "anthropic",
+    "ai",
+    "video",
+    "captions"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexadark/youtube-transcript-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alexadark/youtube-transcript-mcp/issues"
+  },
+  "homepage": "https://github.com/alexadark/youtube-transcript-mcp#readme",
+  "author": "alexadark",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "youtube-transcript-plus": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}