YouTube Transcript to Article

Turn spoken YouTube content into structured Markdown you can publish, quote, or refine further. The web app and HTTP API send captions (and optional metadata) through an OpenAI-compatible chat model—OpenAI or LocalAI—so you control depth, length, language, and model from one place. The same container can also run as an MCP server that returns transcript and video description only, so your assistant writes the article and no API key is required inside the MCP process.

Features

• Transcripts: Resolves a video from a URL or ID, fetches captions, and trims very long text to protect context limits.
• Depth levels: Brief, standard, detailed, or comprehensive instructions to the model (legacy summary / detailed still accepted).
• Word-target summary: Optional “approximately N words” constraint (about ±10%) for tight summaries.
• Model choice: Per-request or default model name (e.g. gpt-4o-mini).
• Host choice: OpenAI, or LocalAI (any OpenAI-compatible server) via base URL.
• Web UI: Simple form at / with the same options as the API.
• MCP server: Same image can run as a Model Context Protocol server that exposes transcript and/or video description/metadata only (no LLM in the container).

Requirements

• Docker (optional) or Python 3.10+
• An API key for OpenAI, or a LocalAI instance that does not require a real key (configure as needed)

Configuration (environment variables)

MCP (Model Context Protocol) environment

The MCP server does not call OpenAI or any other LLM. It only returns YouTube captions and/or title, channel, and description from the watch page so the host assistant can draft an article or summary. No OPENAI_API_KEY is required for MCP.

Set MCP_TRANSPORT before starting Python so the listen address is applied correctly (e.g. export MCP_TRANSPORT=streamable-http then python mcp_server.py).

Tools

• get_youtube_transcript — caption text plus video_title, video_description, and channel (JSON string).
• get_youtube_video_description — title, channel, and description from the watch page only (no captions API; useful if transcripts are disabled).

Local (stdio)

python mcp_server.py

Local (HTTP) — MCP Inspector / streamable HTTP clients:

export MCP_TRANSPORT=streamable-http
python mcp_server.py
# Endpoint (default path): http://127.0.0.1:8000/mcp

Docker (streamable HTTP)

docker run --rm -p 8000:8000 \
  -e APP_MODE=mcp \
  ghcr.io/patrickstigler/youtube-transcript-to-article:latest

Point your MCP client at http://localhost:8000/mcp (or your host) if it supports streamable HTTP.

Docker (stdio) — -i attaches stdin:

docker run --rm -i -e APP_MODE=mcp -e MCP_TRANSPORT=stdio ghcr.io/patrickstigler/youtube-transcript-to-article:latest

Cursor — stdio via Docker (-i required):

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "APP_MODE=mcp",
        "-e", "MCP_TRANSPORT=stdio",
        "ghcr.io/patrickstigler/youtube-transcript-to-article:latest"
      ]
    }
  }
}

Docker

# Docker Hub (replace with your namespace if different)
docker pull patrickstigler/youtube-transcript-to-article
docker run -p 5000:5000 -e OPENAI_API_KEY=sk-... patrickstigler/youtube-transcript-to-article

# GHCR (after logging in: echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin)
docker pull ghcr.io/patrickstigler/youtube-transcript-to-article:latest
docker run -p 5000:5000 -e OPENAI_API_KEY=sk-... ghcr.io/patrickstigler/youtube-transcript-to-article:latest

CI: build and push

Workflow: .github/workflows/docker-publish.yml.

GHCR uses the default GITHUB_TOKEN (workflow permission packages: write is already set in the workflow).

Docker Hub — add these repository secrets:

Tags pushed:

• sha-<short-git-sha> on every qualifying run
• latest when the push is to the repository default branch
• v* when you push a matching Git tag (e.g. v1.0.0)

With Docker Compose, set OPENAI_API_KEY in your environment or .env file (see docker-compose.yml).

LocalAI example

Run LocalAI on the host and point the container at it:

environment:
  - OPENAI_API_KEY=not-needed
  - DEFAULT_MODEL_HOST=localai
  - LOCALAI_BASE_URL=http://host.docker.internal:8080/v1

API

POST /api/generate

JSON body:

{
  "video_id": "https://www.youtube.com/watch?v=VIDEO_ID or VIDEO_ID",
  "detail_level": "standard",
  "word_limit": 300,
  "target_lang": "de",
  "model": "gpt-4o-mini",
  "model_host": "openai"
}

• video_id (required): URL or 11-character ID.
• detail_level: brief | standard | detailed | comprehensive. Legacy: summary → brief, detailed unchanged.
• word_limit (optional): Positive integer; response should be about that many words.
• target_lang (optional): ISO language code for the written output.
• model (optional): Defaults to DEFAULT_MODEL.
• model_host: openai | localai — defaults to DEFAULT_MODEL_HOST.

Success response includes article, video_id, video_title, video_description (watch-page text, best-effort), detail_level, model, and model_host. Errors return JSON { "error": "..." } with appropriate HTTP status (400, 404, 422, 429, 502, 503).

POST /api/transcript

Returns raw transcript text for a video (same video_id / target_lang as before), plus video_title and video_description.

GET /api/config

Public defaults for the web UI (model name, host, allowed detail levels). No secrets.

Local development

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
export OPENAI_API_KEY=sk-...
python app.py

MCP (no API key): python mcp_server.py

Open http://127.0.0.1:5000 for the web UI.

The app is also available on unRAID Community Apps as youtube-transcript-to-article.

License

This project uses the MIT License.

Contributing

Contributions are welcome. Please open an issue or pull request.