# yt-knowledge-mcp

Turn YouTube channels into a searchable knowledge base for AI assistants.

`ytk` downloads the transcripts of a channel (YouTube subtitles first, Whisper as fallback), indexes them for semantic search and exposes them through an [MCP](https://modelcontextprotocol.io) server, so Claude Desktop (or any MCP client) can search them and quote the exact fragment with a timestamped link.

## Features

- **Any channel**: register channels by URL and keep them in sync.
- **Subtitles first, Whisper as fallback**: cheap when captions exist, complete when they do not.
- **Semantic search** with ChromaDB and `bge-m3` (multilingual), filterable by channel and date.
- **Cited answers**: every fragment carries `video_id`, time range and a `youtube.com/watch?v=...&t=...s` link.
- **MCP server** with three tools: `list_channels`, `search_transcripts`, `get_transcript_excerpt`.
- **Optional `ytk ask`** to answer a question with Claude, citing fragments.
- **Light core**: the domain, use cases and CLI have no third-party dependencies. Heavy libraries live behind optional extras and are imported lazily.

## Install

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[youtube,search,mcp]"      # subtitles + search + MCP server
# optional extras: whisper, cuda, llm, all, dev
```

## Quick start

```bash
ytk add https://www.youtube.com/@some-channel
ytk update                      # sync transcripts + build the index
ytk search "risk management"    # semantic search from the terminal
```

`ytk update --latest 20` processes only the most recent videos. Run `ytk --help` for every command: `add`, `remove`, `channels`, `sync`, `index`, `update`, `search`, `ask`, `excerpt`, `serve`.

## Use it from Claude Desktop

Add the server to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "yt-knowledge": {
      "command": "/path/to/yt-knowledge-mcp/.venv/bin/python",
      "args": ["-m", "yt_knowledge", "serve"],
      "env": { "YTK_WORKSPACE": "/path/to/yt-knowledge-mcp/workspace" }
    }
  }
}
```

## Configuration

All settings are optional environment variables. The data directory can also be set with `--workspace`.

| Variable | Purpose |
| --- | --- |
| `YTK_WORKSPACE` | Data directory (default `./workspace`) |
| `YTK_SUBTITLE_LANGS` | Preferred subtitle languages |
| `YTK_WHISPER_MODEL`, `YTK_WHISPER_DEVICE`, `YTK_WHISPER_LANGUAGE` | Whisper fallback |
| `YTK_EMBEDDING_MODEL`, `YTK_EMBEDDING_DEVICE` | Embedding model for search |
| `YTK_COOKIES_FROM_BROWSER` | Browser to read cookies from, if YouTube asks for them |
| `YTK_LLM_MODEL` | Claude model used by `ytk ask` (needs `ANTHROPIC_API_KEY`) |

## Your data stays yours

`workspace/` (transcripts, vector index, channel list) is git-ignored. See [docs/sharing.md](docs/sharing.md) for how to share a knowledge base. Respect YouTube's terms of service and the copyright of the channels you archive.

## Development

```bash
pip install -e ".[dev,mcp]"
pytest -q && ruff check . && mypy
```

The architecture is described in [docs/architecture.md](docs/architecture.md).

## License

MIT, see [LICENSE](LICENSE).