Documentation MCP & AI

Model Context Protocol (MCP) Server

OmniGet runs a built-in MCP server on 127.0.0.1. It exposes 37 tools over Streamable HTTP at POST /mcp, protected by a per-install bearer token.

The OmniGet MCP server: 37 tools over Streamable HTTP on 127.0.0.1.

OmniGet includes a built-in Model Context Protocol (MCP) server. It exposes 37 tools to Claude Code, Claude Desktop, Cursor, VS Code, Goose, and Codex.

1. OmniGet MCP Server Architecture

Your agent calls OmniGet's tools directly instead of writing scraping scripts or juggling terminal flags. The MCP server runs on local loopback at http://127.0.0.1:47720/mcp (it binds the first free port between 47720 and 47729).

Local Loopback Security Boundary: The MCP endpoint only binds to 127.0.0.1. External network adapters cannot query this port. Requests are verified using a randomly generated per-install authentication token found in Tools → AI → MCP server, ensuring your local session cookies and files are never exposed remotely.

2. AI Assistant Configuration Snippets

OmniGet prints all of these snippets with your real token on its MCP server settings page, ready to paste for Claude Code, Claude Desktop, Cursor, VS Code, Goose, and Codex. The three most common clients:

claude_desktop_config.json (Claude Desktop)

{
  "mcpServers": {
    "omniget": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:47720/mcp",
        "--header",
        "Authorization: Bearer YOUR_LOCAL_TOKEN"
      ]
    }
  }
}

Cursor IDE (Settings → Features → MCP Servers)

{
  "mcpServers": {
    "omniget": {
      "url": "http://127.0.0.1:47720/mcp",
      "headers": { "Authorization": "Bearer YOUR_LOCAL_TOKEN" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "omniget": {
      "type": "http",
      "url": "http://127.0.0.1:47720/mcp",
      "headers": { "Authorization": "Bearer YOUR_LOCAL_TOKEN" }
    }
  }
}

3. The Claude Code Plugin (claude-plugin/omniget)

For terminal developers using Anthropic's official Claude Code CLI, OmniGet ships a standalone plugin in claude-plugin/omniget that requires no desktop GUI at all.

Claude Code Installation

# 1. Register OmniGet plugin marketplace:

/plugin marketplace add /path/to/omniget/claude-plugin

# 2. Install the omniget plugin:

/plugin install omniget

Claude Code Slash Command	Description & Usage
`/omniget:setup`	Installs yt-dlp, ffmpeg, and omniget-cli prebuilt binaries after one confirmation.
`/omniget:fetch <url> [--audio]`	Downloads high-definition video or extracts pure audio directly to `~/Downloads/omniget`.
`/omniget:transcribe <url\|file>`	Transcribes media offline using local whisper.cpp (or Gemini/OpenAI if configured).
`/omniget:research <url>`	Distills video caption and audio transcript into a structured Markdown research note with `[mm:ss]` timestamps.
`/omniget:doctor`	Diagnostics check: verifies tool installations, browser cookies, and API key environment.

4. 37 Exposed MCP Tools Catalog

When connected over POST /mcp, AI models can call all 37 tools exposed by the desktop app:

Tool Name	Category	Description & Arguments
`download_url`	Downloads	Queues a media URL (video, audio, playlist, course, image) in the Downloads panel. Args: `url`.
`download_enqueue`	Downloads	Queues a URL with specific mode: `video` or `audio`. Args: `url`, `mode`.
`downloads_queue`	Downloads	Lists active/queued items with status, progress %, transfer speed, ETA, and target path. Optional: `status`, `limit`.
`download_status`	Downloads	Inspects one download by ID: state, progress %, ETA, and exact executed yt-dlp command. Args: `download_id`.
`download_cancel`	Downloads	Cancels an active, queued, or paused download item by ID. Args: `download_id`.
`download_pause`	Downloads	Pauses an in-progress transfer. Args: `download_id`.
`download_resume`	Downloads	Resumes a paused download from its exact byte offset. Args: `download_id`.
`youtube_sponsorblock`	YouTube	Retrieves SponsorBlock segments (sponsor, intro, outro, selfpromo) for a YouTube video URL. Args: `url`, `categories`.
`youtube_dislikes`	YouTube	Returns estimated dislike counts and ratings via the Return YouTube Dislike API. Args: `url`.
`transcribe`	Speech	Transcribes audio/video locally with whisper.cpp; outputs text and timed SRT subtitles. Args: `input`, `model`, `language`.
`tts_speak`	Speech	Synthesizes speech using Microsoft Edge neural voices; saves output MP3. Args: `text`, `voice`, `output`.
`pdf_info`	Documents	Inspects PDF metadata: page count, file size, title, author, and text layer presence. Args: `path`.
`pdf_merge`	Documents	Concatenates multiple PDF files into one ordered output document. Args: `inputs`, `output`.
`pdf_split`	Documents	Splits PDF: mode `each`, `every`, `ranges` ("1-3; 4-10"), or `extract` ("1,3,5-7"). Args: `input`, `mode`.
`pdf_text`	Documents	Extracts plain text layer from a PDF file (with optional page range). Args: `path`, `pages`.
`pdf_render`	Documents	Renders PDF pages into PNG or JPG image files at custom DPI. Args: `input`, `pages`, `dpi`, `format`.
`pdf_sanitize`	Security	Rebuilds PDF from raster pixels (Dangerzone-style) stripping embedded scripts, forms, and exploits. Args: `input`, `output_dir`.
`image_resize`	Images	Batch resizes images: mode `width`, `height`, `fit`, or `percent`. Args: `inputs`, `mode`, `value`.
`ocr`	Images	Extracts text from images using local Tesseract OCR engine. Args: `inputs`, `langs`.
`find_duplicates`	Files	Scans directories for duplicate files matching byte-for-byte hashes. Args: `dirs`, `min_size`.
`file_search`	Files	Searches files by name using native system indexes (Everything on Windows, Spotlight on macOS, locate/find on Linux). Args: `query`, `folder`.
`disk_volumes`	System	Returns all mounted disk drives with total, used, and free byte capacities.
`disk_scan`	System	Generates directory size treemap and lists largest files under path. Args: `path`, `depth`.
`clean_scan`	System	Analyzes cache and temporary junk eligible for cleanup without deleting anything.
`startup_items`	System	Enumerates applications registered to launch automatically on system startup.
`installed_apps`	System	Lists installed desktop applications with reported version and disk usage.
`x_post`	Social	Fetches an X / Twitter post (text, author, images, video) by URL or tweet ID. Args: `url`.
`x_thread`	Social	Unrolls an entire X / Twitter thread starting from any post in the chain. Args: `url`.
`x_profile`	Social	Gathers profile analytics for an X handle (engagement metrics, top posts). Args: `handle`, `limit`.
`x_search`	Social	Searches X posts with advanced search operators and feed filter (`latest` or `top`). Args: `query`, `feed`.
`x_trends`	Social	Fetches current trending hashtags and topic volumes.
`instagram_profile`	Social	Fetches Instagram profile metadata and posts using captured extension session cookies. Args: `username`, `account`.
`gallery_download`	Bulk Media	Downloads galleries or profiles via gallery-dl (Pinterest, ArtStation, DeviantArt, Reddit). Args: `url`, `dest`.
`aria2_download`	Bulk Media	Downloads large files via aria2 multi-connection segmented acceleration. Args: `url`, `dest_dir`, `connections`.
`ai_prices`	AI Ledger	Queries live token pricing per million tokens across providers via LiteLLM and models.dev. Args: `query`, `limit`.
`humanize`	AI Tools	Rewrites synthetic AI-sounding text patterns into clear, human editorial prose. Args: `text`.
`ai_keys`	AI Ledger	Lists saved AI API accounts, providers, and verified balances (secret keys are never exposed).

5. CLI Verification & Headless Testing

Check the local bridge and the CLI from your terminal:

Terminal Verification

# 1. Check the local bridge (it answers with {"ok":true,...}):

curl http://127.0.0.1:47720/v1/health

# 2. Preview what a URL offers without downloading:

omniget-cli info "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# 3. Download audio only:

omniget-cli download "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --audio-only

Previous Guide ← Installation Guide Next Guide 36 Course Platforms →