Obsidian Knowledge Pipeline

A Model Context Protocol server that gives any MCP-capable AI coding agent — Claude Code, Codex, Cursor, Windsurf, Cline, … — safe, structured read/write access to an Obsidian vault, and turns YouTube videos into beautifully structured, cross-linked notes.

[Install](#-install) · [Features](#-features) · [See it in action](#-see-it-in-action) · [Tools](#-tools) · [The pipeline](#-the-process-youtube-pipeline) · [Quick start](#-quick-start) · [Architecture](#-architecture) · [Roadmap](#-roadmap)

---

📦 Install

An MCP server isn't a global install — each user registers it once in their own MCP client. The first two steps are the same for every client:

git clone https://github.com/zenobioscastillo1-source/obsidian-knowledge-pipeline
cd obsidian-knowledge-pipeline
uv sync                          # install dependencies
# then set VAULT_PATH in .env to your Obsidian vault's root folder

Then register it with your agent — pick your client:

# Claude Code
claude mcp add obsidian-knowledge-pipeline -- uv --directory "$PWD" run python server.py

# Codex CLI (recent versions; or add the [mcp_servers] block in ~/.codex/config.toml — see Quick start)
codex mcp add obsidian-knowledge-pipeline -- uv --directory "$PWD" run python server.py

After restarting your client, 11 tools (4 vault · 2 YouTube · 3 screenshot · 2 canvas) are available. The 3 prompts (/process-youtube, /analyze-voice, /build-canvas) appear as slash commands in clients that surface MCP prompts (Claude Code, Claude Desktop); in clients that don't yet (e.g. Codex today), drive the same workflows by asking the agent to use the tools. Using Cursor, Windsurf, the MCP Inspector, or plain pip? See [Quick start](#-quick-start). ($PWD works in bash/zsh; on Windows PowerShell use the folder's absolute path.)

> Why it's portable: the server speaks plain MCP over stdio with no provider SDK and no API keys — nothing in it is tied to a specific model or vendor. Any MCP-capable agent that can launch a local stdio server can run it.

---

✨ Features

🎬 YouTube extraction Pull a video's full transcript (with language fallback) and its title/channel/thumbnail — via the public oEmbed endpoint. No API key.

🗂️ Safe vault I/O Search, read, create, and list notes — every path funnelled through one guard so access never escapes your VAULT_PATH.

🧩 One-prompt pipeline The process-youtube prompt drives the whole flow: extract → analyze → write a full, cross-linked note set into your vault.

🎨 Inline SVG diagrams Every module gets a hand-styled diagram inside an Obsidian callout — hub-and-spoke, stacks, journeys, comparisons.

🏷️ Tag deduplication Scans 3 - Tags first and reuses existing concepts, only creating stubs for genuinely new ones — italic *tags:* wikilinks, not hashtags.

📊 Theme Bases The index is a native Obsidian Base per theme — grouped by source, auto-collecting every future note you process under that theme.

🗣️ Write in your voice Opt in and the pipeline analyzes samples of your own writing into a reusable Voice Profile, then writes notes in your tone, rhythm, and diction. Decline and it uses the default house style.

♻️ Analyze once, reuse The Voice Profile is saved to your vault once and reused on every future run (refresh anytime with the analyze-voice prompt). Voice shapes tone only — structure, tables, SVGs, and tags stay intact.

🗺️ Canvas maps The build-canvas prompt turns a whole topic folder into a zoomed-out Obsidian Canvas — colour-coded Group columns of essence cards, joined by a left → right spine. See the subject whole.

📸 Visual capture Pull HD images out of your sources — capture_pdf_page for PDFs and get_youtube_frames for video — saved to the vault with a ready-to-paste, timestamped embed.

---

🖼️ See it in action

What the pipeline actually produces in your vault. Most panels pair a quick schematic (how it works) with a real screenshot from a live vault below it — not mockups of a different app, but the exact artifacts each run leaves behind.

🎨 A graph view, colour-graded by group

The pipeline writes a graph colour-group config, so every kind of note glows its own colour. Themes, source overviews, modules, and tag concepts each get a hue — and because modules share tags, clusters form on their own.

↑ The real thing — a live vault of ~1,000 notes, each coloured by its group.

📊 Indexing with a live Obsidian Base

Each theme gets one .base — a saved query that filters on theme, groups every note by source, and shows each module's summary. Created once; every future video under that theme drops into the index on its own.

↑ The real thing — a Claude AI API base, 194 notes grouped by source with a “what it covers” column.

🏷️ A Tags folder that explains itself

Tags here aren't hashtags — each is a real note that defines the concept, with aliases and links. The pipeline scans 3 - Tags first and reuses what's there, only stubbing genuinely new ideas, so the vocabulary stays shared and deduped.

↑ The real thing — the Value Creation tag note: a definition, its graph colour, and linked mentions from the modules that use it.

🗺️ A whole topic on one Canvas

build-canvas clusters a folder into colour-coded Group columns of essence cards — each a clickable [[wikilink]] plus a faithful, auto-sized summary — joined by a left → right spine that follows the source's own parts. Zoom out (Shift+1) and see the subject whole.

↑ The real thing — Dan Koe's Purpose & Profit mapped into three columns: reframe money → find direction → create.

🗣️ Notes written in your own voice

Drop a few of your own writings in once; analyze-voice distils them into a reusable Voice Profile. After that every note sounds like you — same facts, your tone and rhythm — while the structure (frontmatter, tables, SVGs, tags, footnotes) stays exactly as specified.

🎞️ The frames that matter, pulled from a video

get_youtube_frames samples a video at scene-changes (or a fixed interval), saves each frame HD to the vault, and hands back a timestamped embed — full-res for you to read, a downscaled copy for the model to caption cheaply.

↑ The real thing — captured frames embedded step-by-step in a Runner Mobility Routine note, right above the instructions they illustrate.

---

🔧 Tools

Vault

| Tool | What it does | Parameters | | --- | --- | --- | | search_vault | Find notes by filename, or by content | query (required); folder, search_content (default false), max_results (default 10) | | read_note | Read a note's full content + metadata | path (required) | | create_note | Create a note, making parent folders as needed | path, content (required); overwrite (default false) | | list_folder | List files and subfolders of a vault directory | path (default "" = vault root); recursive (default false) |

All vault paths are relative to the vault root (e.g. 3 - Tags/Zettelkasten.md). Anything that tries to escape the vault (absolute paths, .., symlinks pointing outside) is rejected.

YouTube

| Tool | What it does | Parameters | | --- | --- | --- | | get_youtube_transcript | Extract a video's transcript (timed segments + concatenated text) | url (required); language (default "en", falls back to the first available, preferring human-made captions) | | get_youtube_metadata | Fetch a video's title, channel name + URL, and thumbnail | url (required) |

url accepts any common form (watch?v=, youtu.be/, embed/, shorts/, with extra &t= / &list= params).

Screenshots (visual capture)

For visual learners (medical students, artists, anyone who learns from diagrams): turn a part of a source into an HD image saved in the vault and ready to embed in the matching note. The full-resolution image is saved for the reader; a downscaled copy is what the model sees (accurate captions, lower token cost). Each saved image comes with an Obsidian embed snippet that names where in the source it came from (page number / timestamp).

| Tool | What it does | Parameters | | --- | --- | --- | | capture_pdf_page | Render PDF page(s) — or a cropped region of a page — to an HD PNG | pdf_path (required; absolute path or vault-relative); pages (default "1", e.g. "12-14" / "3,5,9"), source_name, region ("x0,y0,x1,y1" fractions), dpi (default 300), page_label_offset (default 0), analysis_width (default 1024), embed_width (default 480), save (default true), return_images (default true) | | get_youtube_frames | Sample frames from a video (scene-change or fixed interval) | url (required); mode ("scene" / "interval"), interval_seconds (default 30), scene_threshold (default 0.4), max_frames (default 12), start, end, source_name, analysis_width, embed_width, save, return_images | | crop_screenshot | Crop an already-saved screenshot to just the part you want (fix a capture without re-rendering) | image_path (required; the saved_path a capture returned), region (required; "x0,y0,x1,y1" fractions to KEEP); replace (default false → writes " cropped.png"), analysis_width, embed_width, return_image |

Images save to one central folder (default 2 - Source Material/Screenshots, override with the SCREENSHOTS_FOLDER env var). Each saved image returns an Obsidian embed snippet sized to embed_width (![[img|480]]) so it appears as a readable thumbnail rather than taking over the note — the saved file stays full resolution (click to enlarge). Captions use the printed page number when the PDF embeds page labels (so p.35 matches the book, not the raw PDF index); for label-less PDFs, set page_label_offset to align them (e.g. -12). capture_pdf_page and crop_screenshot are pure Python (PyMuPDF / Pillow) and need no system binaries. get_youtube_frames uses yt-dlp + ffmpeg; both install with the package — imageio-ffmpeg ships a static ffmpeg binary, so no separate ffmpeg install is required (a system ffmpeg on PATH is used in preference if you have one).

Canvas

Turn a folder of notes into a holistic Obsidian Canvas map. The tool owns the layout maths (column geometry, card auto-sizing, the spine edges); the model owns the intelligence (how to cluster the notes, what to call each region). Drive it with the [build-canvas](#-the-process-youtube-pipeline) prompt.

| Tool | What it does | Parameters | | --- | --- | --- | | create_canvas | Write a .canvas from an index hub + colour-coded Group columns of essence cards, auto-laying out positions, sizes, and spine edges | path, title, columns (required); subtitle, index_note, links | | read_canvas | Read a .canvas back as parsed JSON + a short summary (since read_note only accepts .md) | path (required) |

Each column is {label, color, question, notes:[{file, id, summary}]}; colours follow Obsidian's Canvas palette ("1" red … "6" purple) and adjacent columns differ. Every note path must already exist — the tool refuses to point a card at a missing file.

---

🚀 The process-youtube pipeline

One MCP prompt orchestrates the tools into a full video → vault workflow.

It splits the transcript into 3–7 cross-linked modules (each with an SVG diagram, beginner-friendly rewrites, tables, and italic *tags:* wikilinks), writes a per-source overview note, dedupes and creates tag stubs, and maintains a per-theme Obsidian Base index.

| Argument | Required | Description | | --- | --- | --- | | url | ✅ | YouTube video URL | | theme | — | Theme that groups this note's Base (e.g. AI, Trading). Inferred from the video if omitted. | | topic_name | — | Source/course title (used as the source property + overview note name). Derived from the video title if omitted. | | target_folder | — | Subfolder within 6 - Main Notes (defaults to the source title). | | voice | — | mine to write in your own voice (see analyze-voice), default for the house style. Leave blank to be asked. |

> Where it lands: module notes + a — Overview note in 6 - Main Notes/, new concept stubs in 3 - Tags/, and a .base in 4 - Indexes/. Each note carries YAML frontmatter (theme, source, type, module, summary); the theme Base filters on theme, groups by source, and shows each module's summary. Because a Base is a live query, it's created once and every future video under that theme appears in it automatically.

In Claude Code or Claude Desktop, invoke it as a prompt/slash command (e.g. /process-youtube) and supply the URL.

Two companion prompts round out the workflow: analyze-voice builds (or refreshes) the reusable Voice Profile the pipeline writes in, and build-canvas turns an already-processed topic folder into a zoomed-out [Canvas map](#-a-whole-topic-on-one-canvas).

---

🏁 Quick start

Dependencies are managed with uv.

uv sync

> Prefer plain pip? python -m venv .venv; .\.venv\Scripts\Activate.ps1; pip install -r requirements.txt

Point it at your vault — open .env and set the absolute path to your Obsidian vault root:

VAULT_PATH=D:\Obsidian\My Vault

No quotes needed even with spaces; .env is git-ignored. On macOS/Linux use a forward-slash path.

Optional: ignore personal folders

Top-level folders that aren't part of the pipeline can be hidden from list_folder, search_vault, and processing. Set IGNORED_FOLDERS in .env (comma-separated); it defaults to 7 - File Vault, 8 - Quests. Ignored folders are skipped in sweeps but still reachable if you target one directly.

Try it in the MCP Inspector

uv run mcp dev server.py

Opens a browser UI (needs Node.js / npx on your PATH). Try list_folder with no arguments, or open the Prompts tab to run process-youtube.

Connect to Claude Code

claude mcp add obsidian-knowledge-pipeline -- uv --directory "ABSOLUTE\PATH\TO\obsidian-knowledge-pipeline" run python server.py

Connect to Claude Desktop

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

{
  "mcpServers": {
    "obsidian-knowledge-pipeline": {
      "command": "uv",
      "args": ["--directory", "ABSOLUTE/PATH/TO/obsidian-knowledge-pipeline", "run", "python", "server.py"]
    }
  }
}

If uv isn't on Claude Desktop's PATH, point command straight at .venv/Scripts/python.exe (Windows) or .venv/bin/python (macOS/Linux) with server.py as the only arg. Restart Claude Desktop after saving.

Connect to Codex

Recent Codex CLI versions accept the same one-liner as Claude Code:

codex mcp add obsidian-knowledge-pipeline -- uv --directory "ABSOLUTE\PATH\TO\obsidian-knowledge-pipeline" run python server.py

Or edit ~/.codex/config.toml by hand

[mcp_servers.obsidian-knowledge-pipeline]
command = "uv"
args = ["--directory", "ABSOLUTE/PATH/TO/obsidian-knowledge-pipeline", "run", "python", "server.py"]

If uv isn't on Codex's PATH, point command at .venv/Scripts/python.exe (Windows) or .venv/bin/python (macOS/Linux) with server.py as the only args entry. Codex currently surfaces the tools; run the process-youtube / analyze-voice / build-canvas workflows by asking the agent to use them (the prompt logic lives server-side, so the tool calls are identical).

Connect to any other MCP client

Cursor, Windsurf, Cline, Zed and similar all register a local stdio server the same way — a command plus args. Use the same launch command everywhere:

command: uv
args:

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zenobioscastillo1-source](https://github.com/zenobioscastillo1-source)
- **Source:** [zenobioscastillo1-source/obsidian-knowledge-pipeline](https://github.com/zenobioscastillo1-source/obsidian-knowledge-pipeline)
- **License:** MIT

Install and usage instructions live in the source repository linked above.