Skip to main content
Glama

Why vink?

Most "YouTube to notes" tools summarize. An hour of teaching becomes a page, and the examples, steps and asides that made the video worth watching are gone.

vink does the opposite. It takes the full transcript YouTube already has, turns it into readable, timestamped text, and hands it to your AI assistant one part at a time, so nothing is lost when notes are written.

Typical summarizer

vink

A 1-hour lecture becomes

A few bullet points

Complete notes, section by section

Examples and steps

Mostly dropped

Kept, in order

Jump back to the video

Rarely

Every paragraph links to its timestamp

Your notes app

Copy and paste

Markdown with front matter, ready for Obsidian

Setup

Account and API key

uvx vink. No key needed

Related MCP server: YouTube Data MCP Server

Features

Quickstart

1. Install (Python 3.11+):

uv tool install vink        # or: pipx install vink

2. Get a transcript:

vink transcript https://youtu.be/aircAruvnKk
/your/folder/output/But what is a neural network Deep learning chapter 1.md

3. Open the file. It looks like this:

---
title: "But what is a neural network? | Deep learning chapter 1"
channel: "3Blue1Brown"
language: "en"
captions: "manual"
duration: "18:25"
---

# But what is a neural network? | Deep learning chapter 1

**Channel:** 3Blue1Brown · **Duration:** 18:25 · **Language:** English (creator captions)

## Transcript

**[0:04](https://youtu.be/aircAruvnKk?t=4)** This is a 3. It's sloppily written and rendered
at an extremely low resolution of 28x28 pixels, but your brain has no trouble ...

**[0:49](https://youtu.be/aircAruvnKk?t=49)** But if I told you, hey, sit down and write for me
a program that takes in a grid of 28x28 pixels ...

Use it with your AI assistant

vink includes an MCP server. Your assistant reads the transcript part by part and writes full notes, with no API key and nothing extra to pay.

Claude Desktop

Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude:

{
  "mcpServers": {
    "vink": {
      "command": "uvx",
      "args": ["vink", "mcp"]
    }
  }
}

Then ask:

Make detailed notes from https://youtu.be/aircAruvnKk in Hinglish and save them.

Or choose + → Add from vink → make_notes.

claude mcp add vink --scope user -- uvx vink mcp

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "vink": { "command": "uvx", "args": ["vink", "mcp"] }
  }
}
code --add-mcp '{"name":"vink","command":"uvx","args":["vink","mcp"]}'

Most clients accept the standard block:

{
  "mcpServers": {
    "vink": { "command": "uvx", "args": ["vink", "mcp"] }
  }
}

If the client cannot find uvx, use its full path (run which uvx).

What your assistant can do

Tool

What it does

list_languages

Lists the caption languages a video has

get_video_info

Title, language, duration and number of parts

get_chunk

One part of the transcript, as Markdown

get_transcript

The whole transcript, for short videos

save_transcript

Saves the transcript as a Markdown file

save_notes

Saves the notes your assistant wrote

Two note styles are included: detailed-notes, complete study notes (the default), and clean-transcript, an edited transcript that stays close to word for word. Files are saved to ~/Documents/vink unless you set VINK_OUTPUT_DIR.

More details: docs/mcp.md.

Command line

vink transcript URL   Save a transcript as Markdown
vink languages URL    List the caption languages a video has
vink mcp              Run the MCP server
# Hindi if available, otherwise English
vink transcript https://youtu.be/VIDEO_ID --lang hi,en

# The language spoken in the video, printed to the terminal
vink transcript VIDEO_ID --lang original --stdout
vink transcript URL [--lang en,hi] [--output-dir DIR] [--format markdown] [--stdout]
                    [--translate | --no-translate] [--cache | --no-cache]
vink languages URL [--cache | --no-cache]
vink mcp [--transport stdio|http] [--host HOST] [--port PORT] [--insecure-no-auth]
vink [-v | --verbose] [--version] COMMAND

Option

Meaning

--lang

Preferred languages, most preferred first. original means the spoken language.

--stdout

Print instead of saving a file.

--no-translate

Never fall back to YouTube's machine translation.

--no-cache

Fetch fresh data from YouTube.

-v

Show progress logs (place it before the command).

Exit codes: 0 success, 1 the transcript could not be fetched, 2 invalid input or options.

Running on a server

YouTube blocks most requests from cloud servers (AWS, GCP, hosted sandboxes). On your own computer everything just works. For servers, pick one of these:

Host at home

Residential proxy

Idea

Run vink on a home machine; connect to it over HTTPS

Run vink anywhere; send YouTube traffic through a proxy

Cost

Free

Paid proxy plan

Key setting

VINK_AUTH_TOKEN

VINK_PROXY_URL

Host at home:

VINK_AUTH_TOKEN='a-long-random-secret' vink mcp --transport http --port 8000

Residential proxy:

VINK_PROXY_URL='http://user:pass@proxy.example.com:8080' vink mcp

Webshare rotating residential proxies are supported out of the box via VINK_WEBSHARE_USERNAME and VINK_WEBSHARE_PASSWORD.

The step-by-step guide covers Cloudflare Tunnel, systemd and troubleshooting: docs/hosting.md.

Configuration

Everything works without configuration. To change a default, set an environment variable or put it in a .env file:

Variable

Default

What it does

VINK_LANGUAGES

en

Preferred languages, comma-separated

VINK_OUTPUT_DIR

./output (CLI), ~/Documents/vink (MCP)

Where files are saved

VINK_CHUNK_SECONDS

600

Length of one part for get_chunk

VINK_PROXY_URL

none

Proxy for requests to YouTube

VINK_AUTH_TOKEN

none

Token required by the HTTP server

All settings: docs/configuration.md.

How it works

YouTube URL
   │
   ├─ pick the best caption track   (your languages · creator > auto > translated)
   ├─ fetch and cache it
   ├─ clean it into paragraphs       (noise removed · timestamps kept)
   ├─ split it into ~10-minute parts
   └─ Markdown file  ──or──  MCP tools → your AI assistant → detailed notes

Fetching, rendering and saving each sit behind a small interface, so new formats (PDF, DOCX) and destinations (Notion, Obsidian) can be added without touching the core. See docs/architecture.md.

FAQ

No. The official YouTube Data API only lets you download captions for videos you own. vink reads the same caption data YouTube's own player uses, through the open-source youtube-transcript-api library.

Not yet. vink needs either creator-uploaded or auto-generated captions. Transcribing the audio of videos without captions is planned.

Yes. The transcript can be in any language the video has, and the make_notes prompt can write the notes in any language you name, including Hinglish.

You are running vink on a cloud server, and YouTube blocks data-center IP addresses. See Running on a server.

Contributing

Contributions are welcome: bug reports, new output formats, destinations and note styles. See CONTRIBUTING.md to get started.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible assistants to retrieve caption text from YouTube videos as either plain text or timestamped snippets for reading, summarizing, or searching. Supports local stdio and stateless HTTP deployments for integration with Claude Desktop, Claude Code, Cursor, and similar clients.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP clients and agents to fetch YouTube transcripts and caption lists from video IDs or links, preferring manual/auto captions by ordered language preference and falling back to local Faster-Whisper audio transcription when captions are unavailable. Results include source, language, full text and timestamped segments, with CLI exports to JSON, text, SRT and WebVTT, all without paid APIs or API keys.
      3
      MIT