ytlens

Let your AI assistant actually watch YouTube. ytlens is an MCP server that sends a YouTube video to Google Gemini, which looks at the frames and listens to the audio. Answers cover slides, code on screen, UI walkthroughs, charts and demos, not just the captions.

Works with Claude Code (local and cloud sessions), Claude Desktop, Cursor and any other MCP client.

Tools

Options shared by the video tools:

Related MCP server: yt-analysis-mcp

You need

• A Gemini API key from Google AI Studio (the free tier works)

• Node.js 20 or newer

Only public and unlisted videos can be analyzed. The free tier allows about 8 hours of YouTube video per day, and free-tier data may be used by Google to improve its products.

The server is a single self-contained file (dist/ytlens.mjs) with no dependencies, so it starts in about a second straight from GitHub.

Setup

Claude Code cloud sessions (claude.ai/code)

Cloud sessions only see what is in the repository they run on. Add two files to that project's repository:

1. .mcp.json in the repository root:

   {
     "mcpServers": {
       "ytlens": {
         "command": "npx",
         "args": ["-y", "github:Makkov-design/ytlens#v1.0.0"],
         "env": { "GEMINI_API_KEY": "${GEMINI_API_KEY}" }
       }
     }
   }

2. The skill that teaches Claude how to use the tools, at .claude/skills/ytlens/SKILL.md:

   curl -fsSL https://raw.githubusercontent.com/Makkov-design/ytlens/v1.0.0/skills/ytlens/SKILL.md \
     --create-dirs -o .claude/skills/ytlens/SKILL.md

Then, at claude.ai/code, open the environment settings, add GEMINI_API_KEY=<your key> to the environment variables, and keep network access on Trusted (it already allows GitHub and *.googleapis.com).

Claude Code on your computer (plugin)

The plugin bundles the server and the skill:

/plugin install ytlens --marketplace Makkov-design/ytlens

Set GEMINI_API_KEY as an environment variable for your user (on Windows: setx GEMINI_API_KEY "<your key>", then restart Claude Code). Optionally set GEMINI_MODEL_NAME.

Or add only the server, without the plugin:

claude mcp add ytlens --scope user --env GEMINI_API_KEY=<your key> -- npx -y github:Makkov-design/ytlens#v1.0.0

On Windows, put cmd /c before npx in the command.

Claude Desktop, Cursor and other clients

{
  "mcpServers": {
    "ytlens": {
      "command": "npx",
      "args": ["-y", "github:Makkov-design/ytlens#v1.0.0"],
      "env": { "GEMINI_API_KEY": "<your key>" }
    }
  }
}

Always pin a version tag (#v1.0.0), so a new release never runs on your machine without you choosing it.

Docker

docker build -t ytlens https://github.com/Makkov-design/ytlens.git#v1.0.0
docker run -i --rm -e GEMINI_API_KEY=<your key> ytlens

Configuration

Tips for long videos

• Gemini samples about one frame per second. A one-hour video at default detail is roughly 1M tokens, the limit of most models, so use detail: "low" or split it with start / end.

• Transcripts are limited by the model's output size; request videos longer than about 30 minutes in parts.

Security

• Only YouTube video URLs are accepted; anything else is rejected before a request is made.

• The API key travels only in request headers to Google and is removed from every error message and log line.

• Video content is untrusted. Gemini is told never to follow instructions found in a video, and every result is labelled as third-party content so the calling assistant treats it as information, not commands.

• Nothing is written to disk; the cache lives in memory only.

See SECURITY.md to report a vulnerability.

Development

npm ci
npm test            # unit and in-memory MCP integration tests
npm run typecheck
npm run bundle      # writes dist/ytlens.mjs; commit it together with the source change
GEMINI_API_KEY=... npm run smoke                                  # live check of every tool on a short public video
GEMINI_API_KEY=... npm run smoke -- <url> --long <url-over-1h>    # also checks clip timestamps past one hour

Code layout: src/youtube.ts (URLs and timestamps), src/prompts.ts (prompts and response schemas), src/analyzer.ts (Gemini client and error mapping), src/cache.ts, src/server.ts (MCP tools), src/index.ts (entry). The Claude Code plugin lives in .claude-plugin/ and skills/.

License

MIT