Ocular Audio MCP server

OcularAudio MCP

An asynchronous Model Context Protocol (MCP) server that gives AI models "eyes and ears" to process web videos. It extracts transcripts and captures screenshots from YouTube and other video platforms.

Features

• Hybrid transcript extraction: Fetches YouTube captions instantly, falls back to local Whisper ASR
• On-demand video screenshots: Captures frames at any timestamp without downloading the full video
• OCR on screenshots: Extract visible text from frames using Tesseract (optional, --ocr flag)
• Cookie authentication: Supports age-restricted and private videos via cookies.txt
• Local caching: Processed videos are cached for instant subsequent lookups
• Async architecture: Non-blocking design keeps MCP clients responsive
• Flexible output: Clipboard, stdout, file, or JSON — your choice

Benchmark

See BENCHMARK.md for performance benchmarks and a deep competitive analysis against all major video transcript, screenshot, and OCR tools in the MCP and CLI ecosystem.

Requirements

• Python 3.9+ (required for list[int] type hints)
• FFmpeg (required by yt-dlp and OpenCV)
• Node.js 18+ (only for the CLI wrapper)
• Tesseract (optional, only for --ocr flag)

Installation

1. Install system dependencies

macOS:

brew install ffmpeg python3
# Optional (for OCR):
brew install tesseract

Windows:

choco install ffmpeg python
# Optional (for OCR):
choco install tesseract

Linux:

sudo apt update && sudo apt install ffmpeg python3 python3-pip
# Optional (for OCR):
sudo apt install tesseract-ocr

2. Install Python packages

pip install -r requirements.txt

Or manually:

pip install mcp youtube-transcript-api yt-dlp opencv-python-headless faster-whisper requests pytesseract

3. Install Node.js CLI (optional)

npm install

Usage

Option A: MCP Server (Recommended)

The MCP server gives AI models direct access to video transcripts and screenshots.

Quick Install — No installation needed. Just add the config to your MCP client below.

Claude Desktop

{
  "mcpServers": {
    "ocular-audio-mcp": {
      "command": "npx",
      "args": ["ocular-audio-mcp"]
    }
  }
}

Config: ~/Library/Application Support/Claude/claudedesktopconfig.json (macOS) or %APPDATA%\Claude\claudedesktopconfig.json (Windows)

Cursor

{
  "mcpServers": {
    "ocular-audio-mcp": {
      "command": "npx",
      "args": ["ocular-audio-mcp"]
    }
  }
}

Config: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

Claude Code

claude mcp add ocular-audio-mcp -- npx ocular-audio-mcp

Codex CLI (OpenAI)

codex mcp add ocular-audio-mcp -- npx ocular-audio-mcp

Gemini CLI

gemini mcp add ocular-audio-mcp npx ocular-audio-mcp --scope user

Windsurf

{
  "mcpServers": {
    "ocular-audio-mcp": {
      "command": "npx",
      "args": ["ocular-audio-mcp"]
    }
  }
}

Config: ~/.codeium/windsurf/mcp_config.json

Zed

{
  "context_servers": {
    "ocular-audio-mcp": {
      "command": "npx",
      "args": ["ocular-audio-mcp"]
    }
  }
}

Config: ~/.config/zed/settings.json

VS Code (GitHub Copilot)

{
  "servers": {
    "ocular-audio-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["ocular-audio-mcp"]
    }
  }
}

Config: .vscode/mcp.json

OpenCode

{
  "mcpServers": {
    "ocular-audio-mcp": {
      "command": "npx",
      "args": ["ocular-audio-mcp"]
    }
  }
}

Config: ~/.opencode/config.json

Cline (VS Code Extension)

{
  "mcpServers": {
    "ocular-audio-mcp": {
      "command": "npx",
      "args": ["ocular-audio-mcp"]
    }
  }
}

Local Development (from source)

Shortened. The full README is on GitHub.