fetchtranscript-mcp 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,3 @@
1
+ """FetchTranscript MCP Server — YouTube transcript tools for AI."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,95 @@
1
+ """Async HTTP client for the FetchTranscript REST API."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ import httpx
8
+
9
+ from .errors import raise_for_status
10
+
11
+ DEFAULT_BASE_URL = "https://api.fetchtranscript.com"
12
+ DEFAULT_TIMEOUT = 30.0
13
+
14
+
15
+ class FetchTranscriptClient:
16
+ """Async wrapper around the FetchTranscript REST API."""
17
+
18
+ def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL):
19
+ self._client = httpx.AsyncClient(
20
+ base_url=base_url.rstrip("/"),
21
+ headers={
22
+ "X-API-Key": api_key,
23
+ "User-Agent": "FetchTranscript-MCP/0.1.0",
24
+ },
25
+ timeout=DEFAULT_TIMEOUT,
26
+ )
27
+
28
+ async def _get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
29
+ response = await self._client.get(path, params=params)
30
+ raise_for_status(response)
31
+ return response.json()
32
+
33
+ # -- Transcripts --
34
+
35
+ async def get_transcript(
36
+ self,
37
+ video_id: str,
38
+ lang: str | None = None,
39
+ format: str | None = None,
40
+ ) -> dict[str, Any]:
41
+ params: dict[str, Any] = {}
42
+ if lang:
43
+ params["lang"] = lang
44
+ if format:
45
+ params["format"] = format
46
+ return await self._get(f"/v1/transcripts/{video_id}", params or None)
47
+
48
+ async def list_languages(self, video_id: str) -> dict[str, Any]:
49
+ return await self._get(f"/v1/transcripts/{video_id}/languages")
50
+
51
+ # -- Videos --
52
+
53
+ async def get_video_metadata(self, video_id: str) -> dict[str, Any]:
54
+ return await self._get(f"/v1/videos/{video_id}")
55
+
56
+ async def get_chapters(self, video_id: str) -> dict[str, Any]:
57
+ return await self._get(f"/v1/videos/{video_id}/chapters")
58
+
59
+ async def get_comments(self, video_id: str, limit: int | None = None) -> dict[str, Any]:
60
+ params: dict[str, Any] = {}
61
+ if limit is not None:
62
+ params["limit"] = limit
63
+ return await self._get(f"/v1/videos/{video_id}/comments", params or None)
64
+
65
+ # -- Channels --
66
+
67
+ async def get_channel_info(self, channel_id: str) -> dict[str, Any]:
68
+ return await self._get(f"/v1/channels/{channel_id}")
69
+
70
+ async def list_channel_videos(
71
+ self,
72
+ channel_id: str,
73
+ limit: int | None = None,
74
+ offset: int | None = None,
75
+ include_shorts: bool | None = None,
76
+ ) -> dict[str, Any]:
77
+ params: dict[str, Any] = {}
78
+ if limit is not None:
79
+ params["limit"] = limit
80
+ if offset is not None:
81
+ params["offset"] = offset
82
+ if include_shorts is not None:
83
+ params["include_shorts"] = include_shorts
84
+ return await self._get(f"/v1/channels/{channel_id}/videos", params or None)
85
+
86
+ # -- Search --
87
+
88
+ async def search_videos(self, query: str, limit: int | None = None) -> dict[str, Any]:
89
+ params: dict[str, Any] = {"q": query}
90
+ if limit is not None:
91
+ params["limit"] = limit
92
+ return await self._get("/v1/search", params)
93
+
94
+ async def close(self) -> None:
95
+ await self._client.aclose()
@@ -0,0 +1,87 @@
1
+ """Error mapping from HTTP responses to domain-specific exceptions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import httpx
6
+
7
+
8
+ class FetchTranscriptError(Exception):
9
+ """Base error for FetchTranscript API."""
10
+
11
+ def __init__(self, message: str, status_code: int | None = None):
12
+ self.message = message
13
+ self.status_code = status_code
14
+ super().__init__(message)
15
+
16
+
17
+ class VideoNotFoundError(FetchTranscriptError):
18
+ """Video was not found or is unavailable."""
19
+
20
+
21
+ class ChannelNotFoundError(FetchTranscriptError):
22
+ """Channel was not found."""
23
+
24
+
25
+ class InvalidVideoIdError(FetchTranscriptError):
26
+ """Invalid video ID format."""
27
+
28
+
29
+ class InsufficientCreditsError(FetchTranscriptError):
30
+ """Not enough credits to make the request."""
31
+
32
+
33
+ class ServiceUnavailableError(FetchTranscriptError):
34
+ """Upstream service is unavailable."""
35
+
36
+
37
+ # Map API error codes to exception classes
38
+ _ERROR_MAP: dict[str, type[FetchTranscriptError]] = {
39
+ "video_not_found": VideoNotFoundError,
40
+ "transcripts_disabled": VideoNotFoundError,
41
+ "no_transcript_found": VideoNotFoundError,
42
+ "channel_not_found": ChannelNotFoundError,
43
+ "invalid_video_id": InvalidVideoIdError,
44
+ "invalid_channel_id": InvalidVideoIdError,
45
+ "insufficient_credits": InsufficientCreditsError,
46
+ "missing_api_key": FetchTranscriptError,
47
+ "invalid_api_key": FetchTranscriptError,
48
+ "service_unavailable": ServiceUnavailableError,
49
+ }
50
+
51
+ _STATUS_MAP: dict[int, type[FetchTranscriptError]] = {
52
+ 400: InvalidVideoIdError,
53
+ 401: FetchTranscriptError,
54
+ 402: InsufficientCreditsError,
55
+ 404: VideoNotFoundError,
56
+ 503: ServiceUnavailableError,
57
+ }
58
+
59
+
60
+ def raise_for_status(response: httpx.Response) -> None:
61
+ """Raise a domain-specific exception if the response indicates an error."""
62
+ if response.is_success:
63
+ return
64
+
65
+ # Try to parse structured error from JSON body
66
+ message = f"HTTP {response.status_code}"
67
+ error_code = None
68
+ try:
69
+ body = response.json()
70
+ if isinstance(body, dict):
71
+ error_code = body.get("error")
72
+ message = body.get("message", message)
73
+ # Handle FastAPI detail format
74
+ if "detail" in body and isinstance(body["detail"], dict):
75
+ error_code = body["detail"].get("error", error_code)
76
+ message = body["detail"].get("message", message)
77
+ except Exception:
78
+ message = response.text or message
79
+
80
+ # Find the right exception class
81
+ exc_class = FetchTranscriptError
82
+ if error_code and error_code in _ERROR_MAP:
83
+ exc_class = _ERROR_MAP[error_code]
84
+ elif response.status_code in _STATUS_MAP:
85
+ exc_class = _STATUS_MAP[response.status_code]
86
+
87
+ raise exc_class(message, status_code=response.status_code)
@@ -0,0 +1,72 @@
1
+ """MCP prompt templates for common YouTube transcript workflows."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from mcp.server.fastmcp import FastMCP
6
+
7
+
8
+ def register_prompts(mcp: FastMCP) -> None:
9
+ """Register prompt templates on the MCP server."""
10
+
11
+ @mcp.prompt()
12
+ async def summarize_video(video_id: str, lang: str | None = None) -> str:
13
+ """Summarize a YouTube video from its transcript.
14
+
15
+ Args:
16
+ video_id: YouTube video ID (e.g. 'dQw4w9WgXcQ')
17
+ lang: Transcript language code (optional, auto-detected if omitted)
18
+ """
19
+ lang_instruction = f" in {lang}" if lang else ""
20
+ return (
21
+ f"Please summarize the YouTube video with ID `{video_id}`.\n\n"
22
+ f"Steps:\n"
23
+ f"1. First, call `get_video_metadata` for `{video_id}` to get the title and context.\n"
24
+ f"2. Then, call `get_transcript` for `{video_id}`{lang_instruction} to get the full text.\n"
25
+ f"3. Provide a structured summary with:\n"
26
+ f" - **Title and channel**\n"
27
+ f" - **Key points** (bulleted list)\n"
28
+ f" - **Main takeaways** (2-3 sentences)\n"
29
+ f" - **Notable quotes** (if any)\n"
30
+ )
31
+
32
+ @mcp.prompt()
33
+ async def compare_videos(video_ids: str) -> str:
34
+ """Compare multiple YouTube videos on similar topics.
35
+
36
+ Args:
37
+ video_ids: Comma-separated list of video IDs (e.g. 'abc123,def456,ghi789')
38
+ """
39
+ ids = [v.strip() for v in video_ids.split(",") if v.strip()]
40
+ id_list = ", ".join(f"`{v}`" for v in ids)
41
+ return (
42
+ f"Please compare these YouTube videos: {id_list}.\n\n"
43
+ f"Steps:\n"
44
+ f"1. For each video, call `get_video_metadata` to get the title and context.\n"
45
+ f"2. For each video, call `get_transcript` to get the full text.\n"
46
+ f"3. Provide a comparison covering:\n"
47
+ f" - **Topics covered** by each video\n"
48
+ f" - **Key differences** in perspective or approach\n"
49
+ f" - **Common themes** across all videos\n"
50
+ f" - **Which video is best for** different audiences or goals\n"
51
+ )
52
+
53
+ @mcp.prompt()
54
+ async def extract_quotes(video_id: str, topic: str | None = None) -> str:
55
+ """Extract notable quotes from a YouTube video.
56
+
57
+ Args:
58
+ video_id: YouTube video ID
59
+ topic: Optional topic to focus on (e.g. 'machine learning', 'productivity')
60
+ """
61
+ topic_filter = f" related to **{topic}**" if topic else ""
62
+ return (
63
+ f"Please extract key quotes from YouTube video `{video_id}`{topic_filter}.\n\n"
64
+ f"Steps:\n"
65
+ f"1. Call `get_video_metadata` for `{video_id}` to get the title.\n"
66
+ f"2. Call `get_transcript` for `{video_id}` with `format=\"json\"` to get timestamped segments.\n"
67
+ f"3. Identify the most notable, insightful, or impactful quotes{topic_filter}.\n"
68
+ f"4. Present each quote as:\n"
69
+ f" - **[MM:SS]** \"quote text\"\n"
70
+ f" - Brief context of why this quote is notable\n"
71
+ f"\nAim for 5-10 quotes that best represent the video's content.\n"
72
+ )
@@ -0,0 +1,301 @@
1
+ """MCP resource definitions — static documentation exposed to AI clients."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from mcp.server.fastmcp import FastMCP
6
+
7
+
8
+ def register_resources(mcp: FastMCP) -> None:
9
+ """Register documentation resources on the MCP server."""
10
+
11
+ @mcp.resource("fetchtranscript://docs/api-reference")
12
+ async def api_reference() -> str:
13
+ """Complete FetchTranscript API reference."""
14
+ return API_REFERENCE
15
+
16
+ @mcp.resource("fetchtranscript://docs/quickstart")
17
+ async def quickstart() -> str:
18
+ """Getting started with FetchTranscript MCP server."""
19
+ return QUICKSTART
20
+
21
+ @mcp.resource("fetchtranscript://docs/pricing")
22
+ async def pricing() -> str:
23
+ """FetchTranscript pricing and credit system."""
24
+ return PRICING
25
+
26
+ @mcp.resource("fetchtranscript://docs/examples")
27
+ async def examples() -> str:
28
+ """Common workflow examples."""
29
+ return EXAMPLES
30
+
31
+
32
+ # ---------------------------------------------------------------------------
33
+ # Static content
34
+ # ---------------------------------------------------------------------------
35
+
36
+ API_REFERENCE = """\
37
+ # FetchTranscript API Reference
38
+
39
+ Base URL: `https://api.fetchtranscript.com`
40
+
41
+ Authentication: `X-API-Key: yt_xxx` header or `Authorization: Bearer yt_xxx`.
42
+
43
+ All endpoints cost **1 credit** per call (even cache hits). Failed requests (4xx/5xx) cost 0 credits.
44
+
45
+ ---
46
+
47
+ ## Transcripts
48
+
49
+ ### GET /v1/transcripts/{video_id}
50
+ Fetch the transcript of a YouTube video.
51
+
52
+ | Parameter | Type | Default | Description |
53
+ |-----------|--------|---------|-------------|
54
+ | video_id | path | — | 11-char YouTube video ID |
55
+ | lang | query | auto | Language code (e.g. `en`, `it`) |
56
+ | format | query | `json` | `json` (segments), `text` (plain), `srt` |
57
+
58
+ **Response (json format):**
59
+ ```json
60
+ {
61
+ "video_id": "dQw4w9WgXcQ",
62
+ "language": "en",
63
+ "segments": [{"text": "...", "start": 0.0, "duration": 2.5}],
64
+ "is_generated": false,
65
+ "provider": "youtube_transcript_api",
66
+ "metadata": {
67
+ "title": "...", "author": "...", "thumbnail": "...",
68
+ "length_seconds": 212, "view_count": 1400000000,
69
+ "short_description": "..."
70
+ }
71
+ }
72
+ ```
73
+
74
+ ### GET /v1/transcripts/{video_id}/languages
75
+ List available transcript languages.
76
+
77
+ **Response:**
78
+ ```json
79
+ {
80
+ "video_id": "dQw4w9WgXcQ",
81
+ "languages": [
82
+ {"language_code": "en", "language": "English", "is_generated": false, "is_translatable": true}
83
+ ]
84
+ }
85
+ ```
86
+
87
+ ---
88
+
89
+ ## Videos
90
+
91
+ ### GET /v1/videos/{video_id}
92
+ Get video metadata.
93
+
94
+ **Response:** `video_id`, `title`, `description`, `channel_id`, `channel_name`, `duration`, \
95
+ `view_count`, `like_count`, `comment_count`, `upload_date`, `thumbnail_url`, `tags`, `categories`.
96
+
97
+ ### GET /v1/videos/{video_id}/chapters
98
+ Get video chapters.
99
+
100
+ **Response:** `video_id`, `chapters` (list of `{title, start_time, end_time}`), `has_chapters`.
101
+
102
+ ### GET /v1/videos/{video_id}/comments
103
+ Get top comments.
104
+
105
+ | Parameter | Type | Default | Description |
106
+ |-----------|-------|---------|-------------|
107
+ | limit | query | 100 | 1–500 |
108
+
109
+ **Response:** `video_id`, `comments` (list of `{comment_id, text, author, like_count, ...}`), \
110
+ `total_count`, `has_more`.
111
+
112
+ ---
113
+
114
+ ## Channels
115
+
116
+ ### GET /v1/channels/{channel_id}
117
+ Get channel metadata. Accepts `UCxxxxxx` or `@handle` format.
118
+
119
+ **Response:** `channel_id`, `name`, `description`, `subscriber_count`, `video_count`, \
120
+ `thumbnail_url`, `channel_url`.
121
+
122
+ ### GET /v1/channels/{channel_id}/videos
123
+ List channel videos.
124
+
125
+ | Parameter | Type | Default | Description |
126
+ |----------------|-------|---------|-------------|
127
+ | limit | query | 30 | 1–100 |
128
+ | offset | query | 0 | Pagination |
129
+ | include_shorts | query | false | Include Shorts |
130
+
131
+ **Response:** `channel_id`, `videos` (list), `total_count`, `offset`, `limit`, `has_more`.
132
+
133
+ ---
134
+
135
+ ## Search
136
+
137
+ ### GET /v1/search
138
+ Search YouTube videos.
139
+
140
+ | Parameter | Type | Default | Description |
141
+ |-----------|-------|---------|-------------|
142
+ | q | query | — | Search query (1–500 chars) |
143
+ | limit | query | 10 | 1–50 |
144
+
145
+ **Response:** `query`, `results` (list of `{video_id, title, channel_name, duration, view_count, ...}`), \
146
+ `total_results`.
147
+
148
+ ---
149
+
150
+ ## Error Codes
151
+
152
+ | Code | HTTP | Meaning |
153
+ |------|------|---------|
154
+ | `invalid_video_id` | 400 | Video ID is not 11 characters |
155
+ | `invalid_channel_id` | 400 | Invalid channel ID or handle |
156
+ | `missing_api_key` | 401 | No API key provided |
157
+ | `invalid_api_key` | 401 | API key is invalid or inactive |
158
+ | `insufficient_credits` | 402 | No credits remaining |
159
+ | `video_not_found` | 404 | Video does not exist or is private |
160
+ | `transcripts_disabled` | 404 | Video has transcripts disabled |
161
+ | `no_transcript_found` | 404 | No transcript in requested language |
162
+ | `channel_not_found` | 404 | Channel does not exist |
163
+ | `service_unavailable` | 503 | Upstream YouTube error |
164
+
165
+ Error response format:
166
+ ```json
167
+ {"error": "<code>", "message": "<human-readable>"}
168
+ ```
169
+
170
+ ## Response Headers
171
+ - `X-Credits-Remaining` — credits left after the request
172
+ - `X-Processing-Time` — processing time in milliseconds
173
+ """
174
+
175
+ QUICKSTART = """\
176
+ # FetchTranscript MCP — Quick Start
177
+
178
+ ## 1. Get an API Key
179
+
180
+ Sign up at https://fetchtranscript.com and create an API key from the dashboard.
181
+ Keys start with `yt_`.
182
+
183
+ ## 2. Configure your MCP client
184
+
185
+ ### Claude Desktop / Claude Code
186
+
187
+ Add to your MCP settings (`claude_desktop_config.json`):
188
+
189
+ ```json
190
+ {
191
+ "mcpServers": {
192
+ "fetchtranscript": {
193
+ "command": "uvx",
194
+ "args": ["fetchtranscript-mcp"],
195
+ "env": {
196
+ "FETCHTRANSCRIPT_API_KEY": "yt_your_key_here"
197
+ }
198
+ }
199
+ }
200
+ }
201
+ ```
202
+
203
+ ### Cursor
204
+
205
+ Add to `.cursor/mcp.json` in your project:
206
+
207
+ ```json
208
+ {
209
+ "mcpServers": {
210
+ "fetchtranscript": {
211
+ "command": "uvx",
212
+ "args": ["fetchtranscript-mcp"],
213
+ "env": {
214
+ "FETCHTRANSCRIPT_API_KEY": "yt_your_key_here"
215
+ }
216
+ }
217
+ }
218
+ }
219
+ ```
220
+
221
+ ## 3. Try it out
222
+
223
+ Ask your AI assistant:
224
+ - "Get the transcript of this YouTube video: dQw4w9WgXcQ"
225
+ - "What languages are available for video XYZ?"
226
+ - "Search YouTube for 'python async tutorial'"
227
+
228
+ ## Alternative: npm wrapper
229
+
230
+ ```bash
231
+ npx @fetchtranscript/mcp-server
232
+ ```
233
+
234
+ Set `FETCHTRANSCRIPT_API_KEY` as an environment variable.
235
+
236
+ ## Alternative: pip install
237
+
238
+ ```bash
239
+ pip install fetchtranscript-mcp
240
+ FETCHTRANSCRIPT_API_KEY=yt_xxx fetchtranscript-mcp
241
+ ```
242
+ """
243
+
244
+ PRICING = """\
245
+ # FetchTranscript Pricing
246
+
247
+ ## Free Tier
248
+ - **25 credits/month** — no credit card required
249
+ - Resets on the 1st of each month
250
+
251
+ ## Credit Cost
252
+ - Every successful API call costs **1 credit**
253
+ - This applies to all endpoints: transcripts, metadata, chapters, comments, channels, search
254
+ - **Cache hits also cost 1 credit** (transcripts are cached for 30 days)
255
+
256
+ ## What's Free
257
+ - **Failed requests cost 0 credits** — if you get a 4xx or 5xx error, you are not charged
258
+ - Health check endpoint (`/health`) requires no authentication
259
+
260
+ ## Purchasing Credits
261
+ Visit https://fetchtranscript.com/pricing to purchase additional credits.
262
+ Credits never expire.
263
+
264
+ ## Checking Your Balance
265
+ After each API call, check the `X-Credits-Remaining` response header.
266
+ """
267
+
268
+ EXAMPLES = """\
269
+ # FetchTranscript — Common Workflows
270
+
271
+ ## Summarize a Video
272
+ 1. Use `get_video_metadata` to get the title and description
273
+ 2. Use `get_transcript` to get the full text
274
+ 3. Summarize the transcript, referencing the video title
275
+
276
+ ## Compare Multiple Videos
277
+ 1. Use `search_videos` to find videos on a topic
278
+ 2. Use `get_transcript` for each video
279
+ 3. Compare key points, arguments, and perspectives
280
+
281
+ ## Extract Quotes with Timestamps
282
+ 1. Use `get_transcript` with `format="json"` to get segments with timestamps
283
+ 2. Filter segments matching the topic
284
+ 3. Format as `[MM:SS] "quote text"`
285
+
286
+ ## Analyze a Channel
287
+ 1. Use `get_channel_info` to get channel overview
288
+ 2. Use `list_channel_videos` to get recent uploads
289
+ 3. Use `get_video_metadata` on selected videos for deeper analysis
290
+
291
+ ## Research a Topic
292
+ 1. Use `search_videos` to find relevant content
293
+ 2. Use `list_languages` to check subtitle availability
294
+ 3. Use `get_transcript` with specific `lang` for non-English content
295
+ 4. Use `get_comments` to gauge audience reaction
296
+
297
+ ## Video Chapter Navigation
298
+ 1. Use `get_chapters` to get the chapter list
299
+ 2. Use `get_transcript` with `format="json"` for timestamped segments
300
+ 3. Match segments to chapters for section-by-section analysis
301
+ """
@@ -0,0 +1,56 @@
1
+ """FetchTranscript MCP Server entry point."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import sys
7
+
8
+ from mcp.server.fastmcp import FastMCP
9
+
10
+ from .client import FetchTranscriptClient
11
+ from .prompts import register_prompts
12
+ from .resources import register_resources
13
+ from .tools import register_tools
14
+
15
+ mcp = FastMCP(
16
+ "FetchTranscript",
17
+ instructions="Access YouTube transcripts, video metadata, chapters, comments, channels, and search via the FetchTranscript API.",
18
+ )
19
+
20
+ # Lazy-init client so import doesn't fail without env var (tests, --help, etc.)
21
+ _client: FetchTranscriptClient | None = None
22
+
23
+
24
+ def _get_client() -> FetchTranscriptClient:
25
+ global _client
26
+ if _client is None:
27
+ api_key = os.environ.get("FETCHTRANSCRIPT_API_KEY", "")
28
+ if not api_key:
29
+ print(
30
+ "Error: FETCHTRANSCRIPT_API_KEY environment variable is required.\n"
31
+ "Get your API key at https://fetchtranscript.com",
32
+ file=sys.stderr,
33
+ )
34
+ sys.exit(1)
35
+ base_url = os.environ.get(
36
+ "FETCHTRANSCRIPT_BASE_URL", "https://api.fetchtranscript.com"
37
+ )
38
+ _client = FetchTranscriptClient(api_key=api_key, base_url=base_url)
39
+ return _client
40
+
41
+
42
+ # Register components — tools get a lazy client reference
43
+ register_tools(mcp, _get_client) # type: ignore[arg-type]
44
+ register_resources(mcp)
45
+ register_prompts(mcp)
46
+
47
+
48
+ def main() -> None:
49
+ """Run the MCP server (stdio transport)."""
50
+ # Force client init to fail fast if key is missing
51
+ _get_client()
52
+ mcp.run(transport="stdio")
53
+
54
+
55
+ if __name__ == "__main__":
56
+ main()
@@ -0,0 +1,227 @@
1
+ """MCP tool definitions for FetchTranscript."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from collections.abc import Callable
7
+
8
+ from mcp.server.fastmcp import FastMCP
9
+
10
+ from .client import FetchTranscriptClient
11
+ from .errors import FetchTranscriptError
12
+
13
+
14
+ def register_tools(mcp: FastMCP, get_client: Callable[[], FetchTranscriptClient]) -> None:
15
+ """Register all tools on the MCP server instance."""
16
+
17
+ @mcp.tool()
18
+ async def get_transcript(
19
+ video_id: str,
20
+ lang: str | None = None,
21
+ format: str = "text",
22
+ ) -> str:
23
+ """Get the transcript of a YouTube video.
24
+
25
+ Args:
26
+ video_id: YouTube video ID (11 characters, e.g. 'dQw4w9WgXcQ')
27
+ lang: Language code (e.g. 'en', 'it'). Auto-detected if omitted.
28
+ format: Output format — 'text' (default), 'json' (segments with timestamps), or 'srt'.
29
+ """
30
+ try:
31
+ data = await get_client().get_transcript(video_id, lang=lang, format=format)
32
+ except FetchTranscriptError as e:
33
+ return f"Error: {e.message}"
34
+
35
+ if format == "text" and data.get("text"):
36
+ lines = []
37
+ meta = data.get("metadata")
38
+ if meta:
39
+ lines.append(f"**{meta['title']}** by {meta['author']}")
40
+ lines.append("")
41
+ lines.append(data["text"])
42
+ return "\n".join(lines)
43
+
44
+ return json.dumps(data, indent=2)
45
+
46
+ @mcp.tool()
47
+ async def list_languages(video_id: str) -> str:
48
+ """List available transcript languages for a YouTube video.
49
+
50
+ Args:
51
+ video_id: YouTube video ID (11 characters)
52
+ """
53
+ try:
54
+ data = await get_client().list_languages(video_id)
55
+ except FetchTranscriptError as e:
56
+ return f"Error: {e.message}"
57
+
58
+ langs = data.get("languages", [])
59
+ if not langs:
60
+ return "No transcripts available for this video."
61
+
62
+ lines = [f"Available languages for {video_id}:"]
63
+ for lang in langs:
64
+ tag = " (auto-generated)" if lang.get("is_generated") else ""
65
+ lines.append(f"- {lang['language']} ({lang['language_code']}){tag}")
66
+ return "\n".join(lines)
67
+
68
+ @mcp.tool()
69
+ async def get_video_metadata(video_id: str) -> str:
70
+ """Get metadata for a YouTube video (title, description, views, likes, etc.).
71
+
72
+ Args:
73
+ video_id: YouTube video ID (11 characters)
74
+ """
75
+ try:
76
+ data = await get_client().get_video_metadata(video_id)
77
+ except FetchTranscriptError as e:
78
+ return f"Error: {e.message}"
79
+
80
+ lines = [
81
+ f"**{data.get('title', 'Unknown')}**",
82
+ f"Channel: {data.get('channel_name', 'Unknown')}",
83
+ f"Views: {data.get('view_count', 'N/A'):,}" if isinstance(data.get('view_count'), int) else f"Views: {data.get('view_count', 'N/A')}",
84
+ f"Likes: {data.get('like_count', 'N/A'):,}" if isinstance(data.get('like_count'), int) else f"Likes: {data.get('like_count', 'N/A')}",
85
+ f"Duration: {data.get('duration', 'N/A')}s",
86
+ f"Upload date: {data.get('upload_date', 'N/A')}",
87
+ ]
88
+ desc = data.get("description")
89
+ if desc:
90
+ lines.append(f"\nDescription:\n{desc}")
91
+ tags = data.get("tags", [])
92
+ if tags:
93
+ lines.append(f"\nTags: {', '.join(tags)}")
94
+ return "\n".join(lines)
95
+
96
+ @mcp.tool()
97
+ async def get_chapters(video_id: str) -> str:
98
+ """Get chapter list for a YouTube video.
99
+
100
+ Args:
101
+ video_id: YouTube video ID (11 characters)
102
+ """
103
+ try:
104
+ data = await get_client().get_chapters(video_id)
105
+ except FetchTranscriptError as e:
106
+ return f"Error: {e.message}"
107
+
108
+ if not data.get("has_chapters"):
109
+ return "This video has no chapters."
110
+
111
+ lines = [f"Chapters for {video_id}:"]
112
+ for ch in data.get("chapters", []):
113
+ start = int(ch["start_time"])
114
+ mm, ss = divmod(start, 60)
115
+ lines.append(f"- [{mm}:{ss:02d}] {ch['title']}")
116
+ return "\n".join(lines)
117
+
118
+ @mcp.tool()
119
+ async def get_comments(video_id: str, limit: int = 20) -> str:
120
+ """Get top comments on a YouTube video.
121
+
122
+ Args:
123
+ video_id: YouTube video ID (11 characters)
124
+ limit: Number of comments to fetch (default 20, max 500)
125
+ """
126
+ try:
127
+ data = await get_client().get_comments(video_id, limit=limit)
128
+ except FetchTranscriptError as e:
129
+ return f"Error: {e.message}"
130
+
131
+ comments = data.get("comments", [])
132
+ if not comments:
133
+ return "No comments found for this video."
134
+
135
+ lines = [f"Comments for {video_id} ({data.get('total_count', '?')} total):"]
136
+ for c in comments:
137
+ likes = f" [{c['like_count']} likes]" if c.get("like_count") else ""
138
+ pinned = " (pinned)" if c.get("is_pinned") else ""
139
+ lines.append(f"- **{c['author']}**{pinned}{likes}: {c['text']}")
140
+ if data.get("has_more"):
141
+ lines.append(f"\n({len(comments)} shown, more available)")
142
+ return "\n".join(lines)
143
+
144
+ @mcp.tool()
145
+ async def get_channel_info(channel_id: str) -> str:
146
+ """Get information about a YouTube channel.
147
+
148
+ Args:
149
+ channel_id: YouTube channel ID (UCxxxxxx format) or handle (@username)
150
+ """
151
+ try:
152
+ data = await get_client().get_channel_info(channel_id)
153
+ except FetchTranscriptError as e:
154
+ return f"Error: {e.message}"
155
+
156
+ subs = data.get("subscriber_count")
157
+ subs_str = f"{subs:,}" if isinstance(subs, int) else "N/A"
158
+ lines = [
159
+ f"**{data.get('name', 'Unknown')}**",
160
+ f"Subscribers: {subs_str}",
161
+ f"Videos: {data.get('video_count', 'N/A')}",
162
+ f"URL: {data.get('channel_url', 'N/A')}",
163
+ ]
164
+ desc = data.get("description")
165
+ if desc:
166
+ lines.append(f"\n{desc}")
167
+ return "\n".join(lines)
168
+
169
+ @mcp.tool()
170
+ async def list_channel_videos(
171
+ channel_id: str,
172
+ limit: int = 10,
173
+ offset: int = 0,
174
+ include_shorts: bool = False,
175
+ ) -> str:
176
+ """List videos from a YouTube channel.
177
+
178
+ Args:
179
+ channel_id: YouTube channel ID (UCxxxxxx format) or handle (@username)
180
+ limit: Number of videos to return (default 10, max 100)
181
+ offset: Number of videos to skip for pagination (default 0)
182
+ include_shorts: Whether to include YouTube Shorts (default false)
183
+ """
184
+ try:
185
+ data = await get_client().list_channel_videos(
186
+ channel_id, limit=limit, offset=offset, include_shorts=include_shorts
187
+ )
188
+ except FetchTranscriptError as e:
189
+ return f"Error: {e.message}"
190
+
191
+ videos = data.get("videos", [])
192
+ if not videos:
193
+ return "No videos found for this channel."
194
+
195
+ total = data.get("total_count")
196
+ header = f"Videos from channel ({total} total):" if total else "Videos from channel:"
197
+ lines = [header]
198
+ for v in videos:
199
+ views = f" — {v['view_count']:,} views" if isinstance(v.get("view_count"), int) else ""
200
+ lines.append(f"- [{v['video_id']}] {v['title']}{views}")
201
+ if data.get("has_more"):
202
+ lines.append(f"\n(showing {offset + 1}–{offset + len(videos)}, more available)")
203
+ return "\n".join(lines)
204
+
205
+ @mcp.tool()
206
+ async def search_videos(query: str, limit: int = 5) -> str:
207
+ """Search YouTube videos.
208
+
209
+ Args:
210
+ query: Search query string
211
+ limit: Number of results (default 5, max 50)
212
+ """
213
+ try:
214
+ data = await get_client().search_videos(query, limit=limit)
215
+ except FetchTranscriptError as e:
216
+ return f"Error: {e.message}"
217
+
218
+ results = data.get("results", [])
219
+ if not results:
220
+ return f"No results found for '{query}'."
221
+
222
+ lines = [f"Search results for '{query}':"]
223
+ for r in results:
224
+ channel = f" by {r['channel_name']}" if r.get("channel_name") else ""
225
+ views = f" ({r['view_count']:,} views)" if isinstance(r.get("view_count"), int) else ""
226
+ lines.append(f"- [{r['video_id']}] {r['title']}{channel}{views}")
227
+ return "\n".join(lines)
@@ -0,0 +1,145 @@
1
+ Metadata-Version: 2.4
2
+ Name: fetchtranscript-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for FetchTranscript YouTube API
5
+ Author: FetchTranscript
6
+ License-Expression: MIT
7
+ Keywords: ai,mcp,transcript,youtube
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.10
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Requires-Python: >=3.10
15
+ Requires-Dist: httpx>=0.27.0
16
+ Requires-Dist: mcp[cli]>=1.0.0
17
+ Provides-Extra: dev
18
+ Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
19
+ Requires-Dist: pytest>=8.0; extra == 'dev'
20
+ Requires-Dist: respx>=0.22; extra == 'dev'
21
+ Description-Content-Type: text/markdown
22
+
23
+ # FetchTranscript MCP Server
24
+
25
+ An [MCP](https://modelcontextprotocol.io) server that gives AI assistants (Claude Desktop, Cursor, etc.) access to YouTube transcripts, video metadata, channels, and search via the [FetchTranscript](https://fetchtranscript.com) API.
26
+
27
+ ## Features
28
+
29
+ **8 Tools** — get transcripts, list languages, video metadata, chapters, comments, channel info, channel videos, search
30
+
31
+ **4 Documentation Resources** — API reference, quickstart guide, pricing, workflow examples
32
+
33
+ **3 Prompt Templates** — summarize video, compare videos, extract quotes
34
+
35
+ ## Quick Start
36
+
37
+ ### 1. Get an API Key
38
+
39
+ Sign up at [fetchtranscript.com](https://fetchtranscript.com) and create an API key from the dashboard.
40
+
41
+ ### 2. Configure Claude Desktop
42
+
43
+ Add to your `claude_desktop_config.json`:
44
+
45
+ ```json
46
+ {
47
+ "mcpServers": {
48
+ "fetchtranscript": {
49
+ "command": "uvx",
50
+ "args": ["fetchtranscript-mcp"],
51
+ "env": {
52
+ "FETCHTRANSCRIPT_API_KEY": "yt_your_key_here"
53
+ }
54
+ }
55
+ }
56
+ }
57
+ ```
58
+
59
+ ### 3. Use it
60
+
61
+ Ask Claude:
62
+ - "Get the transcript of YouTube video dQw4w9WgXcQ"
63
+ - "Summarize this YouTube video: https://youtube.com/watch?v=..."
64
+ - "Search YouTube for 'machine learning explained' and summarize the top result"
65
+
66
+ ## Configuration for Other Clients
67
+
68
+ ### Cursor
69
+
70
+ Add to `.cursor/mcp.json`:
71
+
72
+ ```json
73
+ {
74
+ "mcpServers": {
75
+ "fetchtranscript": {
76
+ "command": "uvx",
77
+ "args": ["fetchtranscript-mcp"],
78
+ "env": {
79
+ "FETCHTRANSCRIPT_API_KEY": "yt_your_key_here"
80
+ }
81
+ }
82
+ }
83
+ }
84
+ ```
85
+
86
+ ### Claude Code
87
+
88
+ ```bash
89
+ claude mcp add fetchtranscript -- uvx fetchtranscript-mcp
90
+ ```
91
+
92
+ Set `FETCHTRANSCRIPT_API_KEY` in your environment.
93
+
94
+ ## Installation Alternatives
95
+
96
+ ### pip
97
+
98
+ ```bash
99
+ pip install fetchtranscript-mcp
100
+ FETCHTRANSCRIPT_API_KEY=yt_xxx fetchtranscript-mcp
101
+ ```
102
+
103
+ ### npx
104
+
105
+ ```bash
106
+ FETCHTRANSCRIPT_API_KEY=yt_xxx npx @fetchtranscript/mcp-server
107
+ ```
108
+
109
+ ## Tools
110
+
111
+ | Tool | Description | Key defaults |
112
+ |------|-------------|--------------|
113
+ | `get_transcript` | Fetch video transcript | format=text |
114
+ | `list_languages` | Available transcript languages | — |
115
+ | `get_video_metadata` | Video title, views, likes, etc. | — |
116
+ | `get_chapters` | Video chapter list | — |
117
+ | `get_comments` | Top comments | limit=20 |
118
+ | `get_channel_info` | Channel metadata | — |
119
+ | `list_channel_videos` | Videos from a channel | limit=10 |
120
+ | `search_videos` | Search YouTube | limit=5 |
121
+
122
+ ## Environment Variables
123
+
124
+ | Variable | Required | Description |
125
+ |----------|----------|-------------|
126
+ | `FETCHTRANSCRIPT_API_KEY` | Yes | Your API key (starts with `yt_`) |
127
+ | `FETCHTRANSCRIPT_BASE_URL` | No | Override API base URL (default: `https://api.fetchtranscript.com`) |
128
+
129
+ ## Development
130
+
131
+ ```bash
132
+ cd mcp
133
+ pip install -e ".[dev]"
134
+ pytest tests/
135
+ ```
136
+
137
+ Test with MCP Inspector:
138
+
139
+ ```bash
140
+ FETCHTRANSCRIPT_API_KEY=yt_xxx mcp dev src/fetchtranscript_mcp/server.py
141
+ ```
142
+
143
+ ## License
144
+
145
+ MIT
@@ -0,0 +1,11 @@
1
+ fetchtranscript_mcp/__init__.py,sha256=fDM3Vk3AFxRJjBt8AHN5gql0vIHKCq9iy98_A4cEcDo,93
2
+ fetchtranscript_mcp/client.py,sha256=D0lDKT9rABKkFHOfUy2z_S9V2gQ4X2slCx6poG5gcdA,3081
3
+ fetchtranscript_mcp/errors.py,sha256=KDqVZp6JQcxOTETxHtgh_t9sN7a3C82ondsd6A89Sww,2759
4
+ fetchtranscript_mcp/prompts.py,sha256=yFr68ntFmjWWACExzAkQ9gCfOsFL0qIUtLRT68bz1dY,3225
5
+ fetchtranscript_mcp/resources.py,sha256=oypqDHS-UAxdAE5D3fD48l26J6Xux3YtiJeCugRbxi8,8370
6
+ fetchtranscript_mcp/server.py,sha256=evzF26JkPut-DXzutsW9wH0yM1R7hv6uesDE8TvziKk,1616
7
+ fetchtranscript_mcp/tools.py,sha256=PBwuFzJhMIdjxLkCbPNegc3MJxmaEePPbXeBY-gtvXg,8379
8
+ fetchtranscript_mcp-0.1.0.dist-info/METADATA,sha256=IeoLG7vu556SWvdXqvuA_hh8T7M1VOjXbiK562Bm7lA,3644
9
+ fetchtranscript_mcp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
10
+ fetchtranscript_mcp-0.1.0.dist-info/entry_points.txt,sha256=B6VJU_l7nVdquvHIrqYtnACgGGj4b4ikB4dh77GShKI,72
11
+ fetchtranscript_mcp-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.27.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ fetchtranscript-mcp = fetchtranscript_mcp.server:main