youtube-context-mcp 0.2.0__tar.gz

youtube_context_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13', '3.14']
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build

youtube_context_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

youtube_context_mcp-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

youtube_context_mcp-0.2.0/.python-version

@@ -0,0 +1 @@
+3.14

youtube_context_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onur Cetinkol
+
+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.

youtube_context_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: youtube-context-mcp
+Version: 0.2.0
+Summary: A small MCP server for fetching YouTube video transcripts, wrapping youtube-transcript-api
+Project-URL: Homepage, https://github.com/realiti4/youtube-context-mcp
+Project-URL: Repository, https://github.com/realiti4/youtube-context-mcp
+Project-URL: Issues, https://github.com/realiti4/youtube-context-mcp/issues
+Author-email: Onur Cetinkol <onurcetinkol@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: mcp,model-context-protocol,subtitles,transcript,youtube
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: mcp>=1.12
+Requires-Dist: requests>=2.32
+Requires-Dist: youtube-transcript-api<2,>=1.2.4
+Description-Content-Type: text/markdown
+
+# youtube-context-mcp
+
+A small [MCP](https://modelcontextprotocol.io) server that lets agents read YouTube video
+transcripts so you can ask questions about a video, summarize it, or pull quotes.
+
+It's a thin wrapper around [`youtube-transcript-api`](https://github.com/jdepoix/youtube-transcript-api),
+which does all the actual fetching. This project just exposes it as two MCP tools.
+
+> It returns a video's **existing captions/subtitles** — it does **not** transcribe audio
+> (no Whisper/ASR). Videos without captions have nothing to return.
+
+## Install
+
+Run it on demand with [uv](https://docs.astral.sh/uv/) (no install needed):
+
+```bash
+uvx youtube-context-mcp
+```
+
+Or install it:
+
+```bash
+pip install youtube-context-mcp
+```
+
+## Use it with an agent
+
+Add it to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "youtube-context": {
+      "command": "uvx",
+      "args": ["youtube-context-mcp"]
+    }
+  }
+}
+```
+
+Or, in Claude Code:
+
+```bash
+claude mcp add youtube-context -- uvx youtube-context-mcp
+```
+
+### Running over HTTP
+
+By default the server talks **stdio** (the client launches it). If your client runs on a
+different host — for example LM Studio on Windows while this server runs in WSL2 — run it as a
+long-lived HTTP server instead and point the client at a URL:
+
+```bash
+youtube-context-mcp --transport http --host 0.0.0.0 --port 8000
+```
+
+Then add it by URL:
+
+```json
+{
+  "mcpServers": {
+    "youtube-context": { "url": "http://localhost:8000/mcp" }
+  }
+}
+```
+
+(`--host 0.0.0.0` makes it reachable from the Windows side; WSL2 forwards `localhost`.)
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `get_transcript(video, languages=["en"], include_timestamps=False, translate_to=None)` | Returns the transcript as text. `video` is a URL or 11-char ID. Set `include_timestamps` for `[mm:ss]` / `[h:mm:ss]` lines; `translate_to` for an ISO language code. |
+| `list_transcripts(video)` | Lists available transcripts (language, code, manual vs auto-generated, translatable) plus the translation targets. Use it when `get_transcript` can't find your language. |
+
+## Proxies (optional)
+
+YouTube blocks most datacenter/cloud IPs, so on a server you may hit `RequestBlocked` /
+`IpBlocked`. Locally this is rarely needed. To route requests through a proxy, set env vars:
+
+| Env var | Purpose |
+| --- | --- |
+| `WEBSHARE_PROXY_USERNAME`, `WEBSHARE_PROXY_PASSWORD` | Use [Webshare](https://www.webshare.io/) rotating residential proxies. |
+| `WEBSHARE_PROXY_LOCATIONS` | Optional CSV of country codes, e.g. `us,de`. |
+| `YT_TRANSCRIPT_HTTP_PROXY`, `YT_TRANSCRIPT_HTTPS_PROXY` | Use a generic HTTP/HTTPS proxy instead. |
+| `YT_TRANSCRIPT_TIMEOUT` | Per-request timeout in seconds (default `20`). |
+
+With no env set, requests go out directly.
+
+## Troubleshooting
+
+- **`RequestBlocked` / `IpBlocked`** — YouTube blocked the IP. Set the proxy env vars above.
+- **No transcript found** — call `list_transcripts` to see which languages exist for that video.
+- **Transcripts disabled** — the uploader turned captions off; nothing can be fetched.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run pytest
+uv run mcp dev src/youtube_context_mcp/server.py --with-editable .   # interactive inspector
+```
+
+## License
+
+MIT
+
+## Credits
+
+All transcript fetching is done by [`youtube-transcript-api`](https://github.com/jdepoix/youtube-transcript-api)
+by Jonas Depoix. This project is just an MCP adapter on top of it.

youtube_context_mcp-0.2.0/README.md

@@ -0,0 +1,112 @@
+# youtube-context-mcp
+
+A small [MCP](https://modelcontextprotocol.io) server that lets agents read YouTube video
+transcripts so you can ask questions about a video, summarize it, or pull quotes.
+
+It's a thin wrapper around [`youtube-transcript-api`](https://github.com/jdepoix/youtube-transcript-api),
+which does all the actual fetching. This project just exposes it as two MCP tools.
+
+> It returns a video's **existing captions/subtitles** — it does **not** transcribe audio
+> (no Whisper/ASR). Videos without captions have nothing to return.
+
+## Install
+
+Run it on demand with [uv](https://docs.astral.sh/uv/) (no install needed):
+
+```bash
+uvx youtube-context-mcp
+```
+
+Or install it:
+
+```bash
+pip install youtube-context-mcp
+```
+
+## Use it with an agent
+
+Add it to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "youtube-context": {
+      "command": "uvx",
+      "args": ["youtube-context-mcp"]
+    }
+  }
+}
+```
+
+Or, in Claude Code:
+
+```bash
+claude mcp add youtube-context -- uvx youtube-context-mcp
+```
+
+### Running over HTTP
+
+By default the server talks **stdio** (the client launches it). If your client runs on a
+different host — for example LM Studio on Windows while this server runs in WSL2 — run it as a
+long-lived HTTP server instead and point the client at a URL:
+
+```bash
+youtube-context-mcp --transport http --host 0.0.0.0 --port 8000
+```
+
+Then add it by URL:
+
+```json
+{
+  "mcpServers": {
+    "youtube-context": { "url": "http://localhost:8000/mcp" }
+  }
+}
+```
+
+(`--host 0.0.0.0` makes it reachable from the Windows side; WSL2 forwards `localhost`.)
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `get_transcript(video, languages=["en"], include_timestamps=False, translate_to=None)` | Returns the transcript as text. `video` is a URL or 11-char ID. Set `include_timestamps` for `[mm:ss]` / `[h:mm:ss]` lines; `translate_to` for an ISO language code. |
+| `list_transcripts(video)` | Lists available transcripts (language, code, manual vs auto-generated, translatable) plus the translation targets. Use it when `get_transcript` can't find your language. |
+
+## Proxies (optional)
+
+YouTube blocks most datacenter/cloud IPs, so on a server you may hit `RequestBlocked` /
+`IpBlocked`. Locally this is rarely needed. To route requests through a proxy, set env vars:
+
+| Env var | Purpose |
+| --- | --- |
+| `WEBSHARE_PROXY_USERNAME`, `WEBSHARE_PROXY_PASSWORD` | Use [Webshare](https://www.webshare.io/) rotating residential proxies. |
+| `WEBSHARE_PROXY_LOCATIONS` | Optional CSV of country codes, e.g. `us,de`. |
+| `YT_TRANSCRIPT_HTTP_PROXY`, `YT_TRANSCRIPT_HTTPS_PROXY` | Use a generic HTTP/HTTPS proxy instead. |
+| `YT_TRANSCRIPT_TIMEOUT` | Per-request timeout in seconds (default `20`). |
+
+With no env set, requests go out directly.
+
+## Troubleshooting
+
+- **`RequestBlocked` / `IpBlocked`** — YouTube blocked the IP. Set the proxy env vars above.
+- **No transcript found** — call `list_transcripts` to see which languages exist for that video.
+- **Transcripts disabled** — the uploader turned captions off; nothing can be fetched.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run pytest
+uv run mcp dev src/youtube_context_mcp/server.py --with-editable .   # interactive inspector
+```
+
+## License
+
+MIT
+
+## Credits
+
+All transcript fetching is done by [`youtube-transcript-api`](https://github.com/jdepoix/youtube-transcript-api)
+by Jonas Depoix. This project is just an MCP adapter on top of it.

youtube_context_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "youtube-context-mcp"
+version = "0.2.0"
+description = "A small MCP server for fetching YouTube video transcripts, wrapping youtube-transcript-api"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.12",
+    "youtube-transcript-api>=1.2.4,<2",
+    "requests>=2.32",
+]
+authors = [{name = "Onur Cetinkol", email = "onurcetinkol@gmail.com"}]
+license = {text = "MIT"}
+keywords = ["youtube", "transcript", "mcp", "model-context-protocol", "subtitles"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/realiti4/youtube-context-mcp"
+Repository = "https://github.com/realiti4/youtube-context-mcp"
+Issues = "https://github.com/realiti4/youtube-context-mcp/issues"
+
+[project.scripts]
+youtube-context-mcp = "youtube_context_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/youtube_context_mcp"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+    "mcp[cli]>=1.12",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

youtube_context_mcp-0.2.0/src/youtube_context_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""A small MCP server for YouTube transcripts, wrapping youtube-transcript-api."""
+
+from importlib.metadata import version
+
+__version__ = version("youtube-context-mcp")
+
+__all__ = ["__version__"]

youtube_context_mcp-0.2.0/src/youtube_context_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m youtube_context_mcp`."""
+
+from youtube_context_mcp.server import main
+
+if __name__ == "__main__":
+    main()

youtube_context_mcp-0.2.0/src/youtube_context_mcp/proxies.py

@@ -0,0 +1,43 @@
+"""Build a youtube-transcript-api proxy config from environment variables.
+
+YouTube blocks most datacenter/cloud IPs, so on a server the underlying library can raise
+``RequestBlocked`` / ``IpBlocked``. These env vars let the user opt into a proxy without any
+code change. With nothing set, requests go out directly.
+"""
+
+from __future__ import annotations
+
+import os
+
+from youtube_transcript_api.proxies import (
+    GenericProxyConfig,
+    ProxyConfig,
+    WebshareProxyConfig,
+)
+
+
+def build_proxy_config() -> ProxyConfig | None:
+    """Return a ``ProxyConfig`` derived from env vars, or ``None`` for direct requests.
+
+    Precedence:
+        1. ``WEBSHARE_PROXY_USERNAME`` + ``WEBSHARE_PROXY_PASSWORD`` -> ``WebshareProxyConfig``
+           (optional ``WEBSHARE_PROXY_LOCATIONS``, a CSV of country codes such as ``us,de``).
+        2. ``YT_TRANSCRIPT_HTTP_PROXY`` / ``YT_TRANSCRIPT_HTTPS_PROXY`` -> ``GenericProxyConfig``.
+    """
+    webshare_user = os.environ.get("WEBSHARE_PROXY_USERNAME")
+    webshare_pass = os.environ.get("WEBSHARE_PROXY_PASSWORD")
+    if webshare_user and webshare_pass:
+        locations = os.environ.get("WEBSHARE_PROXY_LOCATIONS", "")
+        filter_ip_locations = [c.strip() for c in locations.split(",") if c.strip()]
+        return WebshareProxyConfig(
+            proxy_username=webshare_user,
+            proxy_password=webshare_pass,
+            filter_ip_locations=filter_ip_locations or None,
+        )
+
+    http_proxy = os.environ.get("YT_TRANSCRIPT_HTTP_PROXY")
+    https_proxy = os.environ.get("YT_TRANSCRIPT_HTTPS_PROXY")
+    if http_proxy or https_proxy:
+        return GenericProxyConfig(http_url=http_proxy, https_url=https_proxy)
+
+    return None

youtube_context_mcp-0.2.0/src/youtube_context_mcp/server.py

@@ -0,0 +1,114 @@
+"""MCP server exposing YouTube transcript tools over stdio."""
+
+from __future__ import annotations
+
+import argparse
+from typing import TypedDict
+
+from mcp.server.fastmcp import FastMCP
+
+from youtube_context_mcp import transcripts
+
+mcp = FastMCP("youtube-context")
+
+
+class TranscriptInfo(TypedDict):
+    language: str
+    language_code: str
+    is_generated: bool
+    is_translatable: bool
+
+
+class TranslationLanguage(TypedDict):
+    language: str
+    language_code: str
+
+
+class TranscriptListing(TypedDict):
+    transcripts: list[TranscriptInfo]
+    translation_languages: list[TranslationLanguage]
+
+
+@mcp.tool(structured_output=False)
+def get_transcript(
+    video: str,
+    languages: list[str] | None = None,
+    include_timestamps: bool = False,
+    translate_to: str | None = None,
+) -> str:
+    """Fetch a YouTube video's existing captions as text so you can answer questions about it.
+
+    Returns existing captions/subtitles only; it does not transcribe audio. Videos without
+    captions have nothing to return.
+
+    Args:
+        video: A YouTube URL (watch, youtu.be, shorts, embed, live) or an 11-character video ID.
+        languages: Preferred language codes in priority order. Defaults to ["en"].
+        include_timestamps: If true, prefix each line with [mm:ss] (or [h:mm:ss] past an hour).
+        translate_to: Optional ISO language code to translate the transcript into.
+
+    Returns:
+        The transcript as plain text.
+    """
+    return transcripts.get_transcript(
+        video,
+        tuple(languages) if languages else ("en",),
+        include_timestamps,
+        translate_to,
+    )
+
+
+@mcp.tool()
+def list_transcripts(video: str) -> TranscriptListing:
+    """List the transcripts available for a YouTube video.
+
+    Use this when get_transcript can't find your requested language. It reports each available
+    transcript (language, code, whether it's auto-generated, whether it's translatable) plus
+    the set of languages you can pass to get_transcript's translate_to.
+
+    Args:
+        video: A YouTube URL or an 11-character video ID.
+    """
+    return transcripts.list_transcripts(video)
+
+
+def main() -> None:
+    """Console-script entry point.
+
+    Defaults to stdio, for clients that spawn the server themselves. Use ``--transport http``
+    to run a long-lived HTTP server instead, which is handy when the MCP client lives on a
+    different host than the server -- e.g. LM Studio on Windows connecting to this server
+    running in WSL2 at ``http://localhost:8000/mcp``.
+    """
+    parser = argparse.ArgumentParser(prog="youtube-context-mcp", description=main.__doc__)
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "http", "sse"],
+        default="stdio",
+        help="Transport to serve on (default: stdio).",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind for http/sse (default: 127.0.0.1; use 0.0.0.0 to reach it from "
+        "Windows when running in WSL2).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port to bind for http/sse (default: 8000).",
+    )
+    args = parser.parse_args()
+
+    if args.transport == "stdio":
+        mcp.run()
+        return
+
+    mcp.settings.host = args.host
+    mcp.settings.port = args.port
+    mcp.run(transport="streamable-http" if args.transport == "http" else "sse")
+
+
+if __name__ == "__main__":
+    main()