Defuddle Clip MCP

Clip webpages and YouTube transcripts into Obsidian from your AI assistant.

A small, local MCP server powered by Defuddle. No browser extension or API key required.

URL → extract_url → Markdown preview → save_clip → Obsidian

Quick start

You need Node.js 22.12+, an MCP client that supports local stdio servers, and a local Obsidian vault if you want to save notes.

git clone https://github.com/eothL/defuddle-clip-mcp.git
cd defuddle-clip-mcp
npm ci
npm run setup

Setup asks for your vault's absolute path and clipping folder, then generates mcp-config.local.json. Add its server entry to your MCP client's settings without replacing your other servers. For clients with a form or another config format, copy the command, args, and environment variables into the matching fields.

Set the tool timeout to 120 seconds or more, then reconnect the client. Ask:

Extract this URL and save it to my Obsidian vault: [URL]

The client launches the server automatically; you do not need to run npm start separately. Rerun setup if you move the repository or change Node's installation path.

Tools

Tool	Purpose
extract_url	Return readable Markdown, metadata, and a clip ID.
save_clip	Save that clip to your configured vault and optionally open it.

Extract

{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "language": "en",
  "require_transcript": true,
  "force_refresh": false
}

Only url is required. YouTube URLs require a transcript by default. Results include markdown, clip_id, transcript_present, warnings, cached, and extracted_at.

Save

{
  "clip_id": "ID_FROM_EXTRACT_URL",
  "open": true
}

Notes include source properties and a - Defuddle filename suffix. Missing clipping folders are created inside the vault. The server verifies the saved content and never overwrites a different existing note. An identical repeat save returns the existing note.

Clip IDs last for the current server session, up to 20 clips. After restarting, extract the URL again to obtain a new ID; the server can reuse its cache.

Configuration

Environment variable	Default	Description
OBSIDIAN_VAULT_PATH	Unset	Absolute path to an existing local vault. Leave unset for extraction only.
OBSIDIAN_CLIP_FOLDER	Clippings	Folder relative to the vault, such as Materials/Clippings.
DEFUDDLE_CACHE_DIR	~/.cache/defuddle-clip-mcp	Local extracted-content cache.

Configure these in the MCP server environment, then restart the server. The server must run on the computer that holds the vault.

Obsidian need not be running to save. Automatic opening uses its URI handler through macOS open, Windows PowerShell, or Linux xdg-open. If opening fails, the saved note remains available and the tool returns its path and the opening error.

Successful extractions are cached for 24 hours by URL and language. Expired files are ignored, not deleted automatically. Delete the cache directory to remove stored content; use force_refresh to bypass it.

Limitations

• YouTube may rate-limit or block requests. Wait before retrying, or reuse cached results. There is no browser fallback.
• Captions must exist and be accessible. Transcript presence does not prove completeness; descriptions may be truncated.
• Existing notes with different content are preserved. Move or rename one if you want a new extraction saved under the same title.
• This is a local prototype for user-selected public URLs. It has no authentication or private-network/redirect isolation; do not expose it as a public fetching service.
• Extracted content is untrusted source material, never instructions.

Live YouTube extraction and Obsidian opening have been tested on macOS. CI tests the offline MCP workflow across macOS, Windows, and Linux; it does not launch Obsidian or query YouTube.

Development

npm ci
npm test

Tests use a synthetic article and temporary vault. They cover MCP startup, cached extraction, saving, duplicate handling, user-edit preservation, path isolation, and OS opener selection. They do not access a real vault or the network.

src/
  server.mjs          MCP tools, extraction, caching, and saving
  platform.mjs        Vault paths and OS integration
scripts/
  setup.mjs           Interactive MCP configuration
test/
  mcp.test.mjs        Offline integration tests

Share this repository link or use Code → Download ZIP. Each person runs setup on their own computer. Keep generated configuration and cache files private; both are excluded from version control. This package is not published to npm.

License

MIT. Defuddle and other dependencies retain their own licenses. Defuddle is pinned to version 0.19.3; update deliberately and retest before distributing changes.