{
  "markdown": "# OcularAudio MCP\n\n![OcularAudio MCP](OcularAudioMCP.png)\n\nAn 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.\n\n## Features\n\n- **Hybrid transcript extraction**: Fetches YouTube captions instantly, falls back to local Whisper ASR\n- **On-demand video screenshots**: Captures frames at any timestamp without downloading the full video\n- **OCR on screenshots**: Extract visible text from frames using Tesseract (optional, `--ocr` flag)\n- **Cookie authentication**: Supports age-restricted and private videos via cookies.txt\n- **Local caching**: Processed videos are cached for instant subsequent lookups\n- **Async architecture**: Non-blocking design keeps MCP clients responsive\n- **Flexible output**: Clipboard, stdout, file, or JSON — your choice\n\n## Benchmark\n\nSee [BENCHMARK.md](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.\n\n## Requirements\n\n- **Python 3.9+** (required for `list[int]` type hints)\n- **FFmpeg** (required by yt-dlp and OpenCV)\n- **Node.js 18+** (only for the CLI wrapper)\n- **Tesseract** (optional, only for `--ocr` flag)\n\n## Installation\n\n### 1. Install system dependencies\n\n**macOS:**\n```bash\nbrew install ffmpeg python3\n# Optional (for OCR):\nbrew install tesseract\n```\n\n**Windows:**\n```bash\nchoco install ffmpeg python\n# Optional (for OCR):\nchoco install tesseract\n```\n\n**Linux:**\n```bash\nsudo apt update && sudo apt install ffmpeg python3 python3-pip\n# Optional (for OCR):\nsudo apt install tesseract-ocr\n```\n\n### 2. Install Python packages\n\n```bash\npip install -r requirements.txt\n```\n\nOr manually:\n```bash\npip install mcp youtube-transcript-api yt-dlp opencv-python-headless faster-whisper requests pytesseract\n```\n\n### 3. Install Node.js CLI (optional)\n\n```bash\nnpm install\n```\n\n## Usage\n\n### Option A: MCP Server (Recommended)\n\nThe MCP server gives AI models direct access to video transcripts and screenshots.\n\n**Quick Install** — No installation needed. Just add the config to your MCP client below.\n\n#### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"ocular-audio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"ocular-audio-mcp\"]\n    }\n  }\n}\n```\nConfig: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n\n#### Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"ocular-audio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"ocular-audio-mcp\"]\n    }\n  }\n}\n```\nConfig: `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)\n\n#### Claude Code\n\n```bash\nclaude mcp add ocular-audio-mcp -- npx ocular-audio-mcp\n```\n\n#### Codex CLI (OpenAI)\n\n```bash\ncodex mcp add ocular-audio-mcp -- npx ocular-audio-mcp\n```\n\n#### Gemini CLI\n\n```bash\ngemini mcp add ocular-audio-mcp npx ocular-audio-mcp --scope user\n```\n\n#### Windsurf\n\n```json\n{\n  \"mcpServers\": {\n    \"ocular-audio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"ocular-audio-mcp\"]\n    }\n  }\n}\n```\nConfig: `~/.codeium/windsurf/mcp_config.json`\n\n#### Zed\n\n```json\n{\n  \"context_servers\": {\n    \"ocular-audio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"ocular-audio-mcp\"]\n    }\n  }\n}\n```\nConfig: `~/.config/zed/settings.json`\n\n#### VS Code (GitHub Copilot)\n\n```json\n{\n  \"servers\": {\n    \"ocular-audio-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"ocular-audio-mcp\"]\n    }\n  }\n}\n```\nConfig: `.vscode/mcp.json`\n\n#### OpenCode\n\n```json\n{\n  \"mcpServers\": {\n    \"ocular-audio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"ocular-audio-mcp\"]\n    }\n  }\n}\n```\nConfig: `~/.opencode/config.json`\n\n#### Cline (VS Code Extension)\n\n```json\n{\n  \"mcpServers\": {\n    \"ocular-audio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"ocular-audio-mcp\"]\n    }\n  }\n}\n```\n\n#### Local Development (from source)\n\n```json\n{\n  \"mcpServers\": {\n    \"ocular-audio-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"/path/to/ocular_audio_mcp.py\"]\n    }\n  }\n}\n```\n\n### Option B: CLI\n\n```bash\nnpx ocular-audio \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n```\n\nBy default, the transcript is printed to stdout and copied to your clipboard. Paste it into Claude Web, ChatGPT, or any AI chat.\n\n#### CLI Options\n\n| Flag | Description |\n|------|-------------|\n| `-h`, `--help` | Show help message |\n| `-v`, `--version` | Show version number |\n| `--stdout` | Print transcript to stdout only (no clipboard, no file) |\n| `--no-clipboard` | Skip clipboard copy |\n| `--output <file>` | Write context to a specific file path |\n| `--json` | Output raw JSON (metadata + transcript) for programmatic use |\n| `--detail <level>` | Screenshot capture mode: `overview`, `balanced`, `deep`, `auto` (default: `auto`) |\n| `--ocr` | Extract text from screenshots using Tesseract OCR |\n| `--force` | Bypass cache and re-process the video |\n| `--verbose` | Show detailed progress information |\n| `--quiet` | Suppress summary and status messages |\n| `--check` | Check system dependencies (Python, FFmpeg, Whisper, Tesseract) |\n| `--list-cached` | List all cached videos with titles |\n| `--cache-info` | Show cache statistics (count, size, oldest/newest) |\n| `--clear-cache` | Delete all cached transcripts and screenshots |\n\n#### Examples\n\n```bash\n# Basic usage — prints to stdout + copies to clipboard\nnpx ocular-audio \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# Stdout only — great for piping to other tools\nnpx ocular-audio --stdout \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\" | head -50\n\n# Write to a specific file\nnpx ocular-audio --output transcript.txt \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# Raw JSON for programmatic consumption\nnpx ocular-audio --json \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\" | jq .metadata.title\n\n# Transcript only, no screenshots\nnpx ocular-audio --detail overview \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# Maximum screenshots\nnpx ocular-audio --detail deep \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# No clipboard copy, just print to terminal\nnpx ocular-audio --no-clipboard \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# Screenshots with OCR — extract visible text from frames\nnpx ocular-audio --ocr \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# JSON output with OCR\nnpx ocular-audio --json --ocr \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# Force re-process (bypass cache)\nnpx ocular-audio --force \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# Verbose mode — see all progress details\nnpx ocular-audio --verbose \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# Quiet mode — minimal output\nnpx ocular-audio --quiet --stdout \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n# Check system capabilities\nnpx ocular-audio --check\n\n# List cached videos\nnpx ocular-audio --list-cached\n\n# Show cache stats\nnpx ocular-audio --cache-info\n\n# Clear all cached data\nnpx ocular-audio --clear-cache\n```\n\n## Cookie Setup (for age-restricted/private videos)\n\nYouTube may block transcript access for age-restricted or private videos. To fix this, export your browser cookies:\n\n1. Install a browser extension like \"Get cookies.txt LOCALLY\" (Chrome/Firefox)\n2. Go to youtube.com while logged in\n3. Export cookies to a file named `cookies.txt`\n4. Place the file in one of these locations:\n   - `~/.cache/ocular_audio_mcp/cookies.txt`\n   - `~/.config/ocular_audio_mcp/cookies.txt`\n   - `./cookies.txt` (in the project directory)\n\nThe server will automatically detect and use the cookies file.\n\n## MCP Tools\n\n### `get_ocular_audio_capabilities`\n\nReturns system capabilities and dependency status. Use this to check what features are available.\n\n**Parameters:** None\n\n**Returns:** System info including Python version, FFmpeg, Whisper, Tesseract, OpenCV, and cookie status.\n\n### `get_ocular_audio_metadata`\n\nExtracts only video metadata (title, creator, duration, views, chapters) without transcript. Much faster than getting the full transcript.\n\n**Parameters:**\n- `url` (string): Video URL\n\n### `get_ocular_audio_transcript`\n\nExtracts the complete transcript, video chapters, and metadata from a video.\n\n**Parameters:**\n- `url` (string): Video URL\n- `use_local_whisper` (boolean, default: true): Enable Whisper fallback if captions unavailable\n\n### `get_ocular_audio_chapters`\n\nExtracts only video chapters with timestamps. Returns chapter titles with start times in [MM:SS] format.\n\n**Parameters:**\n- `url` (string): Video URL\n\n### `get_ocular_audio_video_screenshots`\n\nCaptures screenshots at specific timestamps.\n\n**Parameters:**\n- `url` (string): Video URL\n- `timestamps_secs` (array of integers): Timestamps to capture (e.g., `[45, 120, 300]`)\n- `enable_ocr` (boolean, default: false): If true, run OCR on each captured frame to extract visible text\n\n### `get_ocular_audio_video_context`\n\nExtracts transcript, metadata, and intelligent screenshots in one call. Automatically analyzes the transcript to find visually important moments and captures screenshots at those timestamps.\n\n**Parameters:**\n- `url` (string): Video URL\n- `detail_level` (string, default: \"auto\"): Controls screenshot capture mode:\n  - `\"auto\"` - Adapts to video length and content importance\n  - `\"overview\"` - Transcript and metadata only, no screenshots (fastest)\n  - `\"balanced\"` - Screenshots only at visually important moments (strong signals)\n  - `\"deep\"` - Screenshots at every visually significant moment (all signals)\n- `use_local_whisper` (boolean, default: true): Enable Whisper fallback if captions unavailable\n- `enable_ocr` (boolean, default: false): If true, run OCR on captured screenshots to extract visible text\n\n### `list_ocular_audio_cache`\n\nLists all cached videos with their metadata (title, uploader, duration, when cached).\n\n**Parameters:** None\n\n### `clear_ocular_audio_cache`\n\nClears cached video data.\n\n**Parameters:**\n- `video_id` (string, optional): Video ID to clear specific video. If empty, clears all cache.\n\n## Cache Management\n\nProcessed videos are cached in `~/.cache/ocular_audio_mcp/` for 7 days. Use the CLI flags to manage the cache:\n\n```bash\nnpx ocular-audio --list-cached     # See what's cached\nnpx ocular-audio --cache-info      # Storage stats\nnpx ocular-audio --clear-cache     # Wipe everything\n```\n\nOr manually:\n```bash\nrm -rf ~/.cache/ocular_audio_mcp/*.json\n```\n\n## Troubleshooting\n\n### \"No local ASR engines found\"\nInstall a Whisper engine:\n```bash\npip install faster-whisper\n```\n\n### \"Audio track download failed\"\n- Check your network connection\n- For age-restricted videos, add a cookies.txt file (see Cookie Setup above)\n- Ensure FFmpeg is installed: `ffmpeg -version`\n\n### \"Failed to extract a playable video stream\"\n- The video may be private or geo-blocked\n- Try adding cookies.txt\n- Check if the video is still available\n\n### Python not found on Windows\nEnsure Python is in your PATH. Try:\n```bash\npython --version\n```\nIf not found, reinstall Python from python.org and check \"Add Python to PATH\" during installation.\n\n### MCP server not connecting\n- Verify the path in your MCP client config is correct\n- Test the server manually: `python /path/to/ocular_audio_mcp.py`\n- Check that all dependencies are installed: `pip list | grep -E \"mcp|whisper|yt-dlp\"`\n\n## License\n\nMIT\n",
  "bytes": 11252,
  "sha": "82219bebb4c6bd78e07e67c0fcb3ba8bb789590d8d93770c09ccf8b0f9e379bf",
  "repo_slug": "rayakaan/ocularaudio-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rayakaan_ocular_audio_mcp_83d9b25d/readme"
}