Video Recognition Bilibili

An MCP (Model Context Protocol) server that analyzes images, audio, and video using Google's Gemini AI.

This is a fork of mario-andreschak/mcp_video_recognition. All original recognition logic and credit belong to the upstream author. This fork adds the changes listed below. Licensed under MIT, same as upstream.

---

What this fork adds / 本 fork 的改动

Compared to the upstream project, this fork adds:

1. URL input for video recognition / 视频识别支持网址输入 The video_recognition tool's filepath argument now accepts either a local file path OR a video URL (e.g. a Bilibili or YouTube link). When a URL is given, the server downloads the video with yt-dlp first, then analyzes it with Gemini, and deletes the temp file afterwards. video_recognition 的 filepath 参数现在既能填本地路径，也能直接填视频网址（B站 / YouTube 等）。传网址时服务端先用 yt-dlp 下载，再交给 Gemini 分析，用完自动删除临时文件。

2. Auto quality selection / 自动选清晰度 Uses yt-dlp -S res:480 to pick the format closest to 480p (works for both landscape and portrait videos), keeping downloads small and fast to save tokens and memory. 用 -S res:480 自动选最接近 480p 的档（横屏竖屏都适配），省流量、省 token、省内存。

3. Cookie & User-Agent support for anti-bot sites / 支持 Cookie 和 UA 绕过风控 If a Netscape-format cookie file exists at /app/bili-cookies.txt, it is passed to yt-dlp automatically (Bilibili and some sites return HTTP 412 without login cookies). A desktop User-Agent is always sent. 若 /app/bili-cookies.txt 存在（Netscape 格式的 cookie 文件），会自动带给 yt-dlp（B站等站点无登录 Cookie 会返回 412）。同时固定发送桌面版 User-Agent。

4. Dockerfile bundles yt-dlp + ffmpeg / Dockerfile 内置 yt-dlp 和 ffmpeg。

Image and audio recognition are unchanged from upstream. 图片和音频识别与上游一致，未改动。

---

Tools

• image_recognition — analyze an image (local file path)
• audio_recognition — analyze / transcribe audio (local file path)
• video_recognition — analyze a video; filepath accepts a local path or a URL

---

Prerequisites

• Docker (recommended), or Node.js 22+
• A Google Gemini API key

---

Quick start (Docker)

git clone <your-fork-url>.git video-mcp
cd video-mcp

# 1. Create env file (see .env.example)
cp .env.example video.env
# then edit video.env and put in your real GOOGLE_API_KEY

# 2. (Optional, for Bilibili) put a Netscape-format cookie file next to the project
#    Export it with a browser extension like "Cookie-Editor" while logged in to Bilibili.
#    Name it bili-cookies.txt

# 3. Build
docker build -t video-mcp .

# 4. Run (mount cookie file if you have one)
docker run -d --name video --restart unless-stopped \
  -p 18014:3000 \
  --env-file ./video.env \
  -v "$(pwd)/bili-cookies.txt:/app/bili-cookies.txt" \
  video-mcp

MCP endpoint: http://<host>:3000/mcp (Streamable HTTP).

Environment variables

Variable	Meaning
GOOGLE_API_KEY	Required. Google Gemini API key.
TRANSPORT_TYPE	sse (Streamable HTTP, for remote) or stdio. Default stdio.
PORT	Port for HTTP transport. Default 3000.
LOG_LEVEL	verbose / debug / info / warn / error / fatal.

---

Usage note

When your MCP client (or its model) calls video_recognition, pass the Bilibili/YouTube link as the filepath argument. Example intent:

Call video_recognition with filepath = https://www.bilibili.com/video/BVxxxxxxxxx/ and tell me what's in the video.

Keep videos short (Gemini free tier has size/quota limits). Cookies expire — re-export when Bilibili starts returning 412 / login errors.

---

Security

• Never commit your real video.env (contains the API key) or bili-cookies.txt (contains your login session). Both are gitignored.
• Downloaded videos are stored in a temp dir and deleted after analysis.

---

中文部署教程（详细版）

这份教程假设你要把它部署到一台**自己的云服务器（Linux）**上，用 Docker 运行，让远程的 MCP 客户端（如各类聊天平台）通过网址调用，实现「发一个 B 站链接，AI 就能看懂视频画面」。

你需要准备

1. 一台装了 Docker 的 Linux 服务器（1核1G 也能跑，处理视频那几秒会吃点内存，建议有 2G 内存或配了 swap）。
2. 一个 Google Gemini API Key：去 aistudio.google.com/apikey 免费申请。
3. （下 B 站视频需要）一份你自己的 B 站登录 Cookie，下面第 4 步会讲怎么导出。

第 1 步：拉代码

cd ~
git clone <你的仓库地址>.git video-mcp
cd video-mcp

第 2 步：写环境变量文件

cp .env.example video.env
nano video.env

把 GOOGLE_API_KEY= 后面换成你自己的 Gemini Key。其它保持默认即可（TRANSPORT_TYPE=sse 表示走 HTTP，适合远程用）。保存退出：Ctrl+O 回车 Ctrl+X。

第 3 步：（可选，但下 B 站视频几乎必需）准备 Cookie

B 站对没有登录 Cookie 的请求会返回 HTTP 412，导致下载失败。解决办法是带上你自己的登录 Cookie：

1. 电脑浏览器登录 B 站（bilibili.com）。
2. 装浏览器扩展 Cookie-Editor，在 B 站页面点开它。
3. 点 Export → Export as Netscape（⚠️ 一定要选 Netscape 格式，不是 JSON）。
4. 把导出的内容保存成服务器上的 ~/video-mcp/bili-cookies.txt：

   nano ~/video-mcp/bili-cookies.txt
   

   粘贴进去保存。文件开头应该是 # Netscape HTTP Cookie File。

Cookie 会过期。哪天视频又下不了（报 412 或要登录），重新导出覆盖这个文件、再 docker restart video 即可。

第 4 步：构建镜像

docker build -t video-mcp .

第一次会下载 Node 基础镜像、安装 ffmpeg 和 yt-dlp、编译代码，需要一两分钟。看到 naming to ... video-mcp 就成功了。

第 5 步：启动容器

docker run -d --name video --restart unless-stopped \
  -p 18014:3000 \
  --env-file ~/video-mcp/video.env \
  -v ~/video-mcp/bili-cookies.txt:/app/bili-cookies.txt \
  video-mcp

说明：

• -p 18014:3000：把容器的 3000 端口映射到服务器的 18014（对外端口你可以改）。
• -v ...bili-cookies.txt...：把 Cookie 文件挂进容器。没做第 3 步（没 Cookie）就删掉这一行 -v。
• 注意挂载 Cookie 不要加 :ro（只读），因为 yt-dlp 运行时会回写更新 Cookie。

第 6 步：确认起来了

docker logs video

看到 Server started with Streamable HTTP transport on port 3000 就正常了。再确认 yt-dlp 装好：

docker exec video yt-dlp --version

能打印版本号（如 2026.07.04）即可。

第 7 步：连接你的 MCP 客户端

MCP 端点是：

http://你的服务器IP:18014/mcp

如果你用了域名 + 反向代理（如 Nginx / Caddy）转发到 localhost:18014，就用你的 https://域名/mcp。传输方式选 Streamable HTTP。

第 8 步：怎么用

在你的聊天客户端里，明确要求调用 video_recognition 工具，把链接作为 filepath 参数。例如对 AI 说：

请调用 video_recognition 工具，filepath 填 https://www.bilibili.com/video/BVxxxxxxxxx/ ，帮我看看视频里是什么。

⚠️ 如果你同时接了「网页读取」类工具（如 jina），AI 可能会把链接拿去读网页而不是下载视频。这时要明确说「不要读网页，用 video_recognition 下载视频看画面」。

常见问题

现象	原因	解决
下载报 HTTP Error 412	B 站风控，没带登录 Cookie	按第 3 步准备 bili-cookies.txt 并挂载
报 Read-only file system: /app/bili-cookies.txt	挂载 Cookie 时加了 :ro	去掉 :ro 重新 run
报 Requested format is not available	视频没有对应清晰度档	本 fork 已用 -S res:480 自动选档，一般不会遇到；若遇到可 docker exec video yt-dlp --list-formats <链接> 看有哪些档
报 429 Too Many Requests / exceeded your current quota	Gemini Key 免费额度用完 / 被限流	换一个 Gemini Key（改 video.env 后 docker restart video），或等次日额度重置
AI 不调用视频工具，去读网页了	客户端优先用了别的工具	对话里点名 video_recognition，或临时停用网页读取类工具

关于视频时长与费用

• 视频识别很吃 Gemini 的 token，建议只处理 1~3 分钟以内的短视频。
• Gemini 有免费额度，个人偶尔用足够；高频使用会触发限流或产生费用。
• 本 fork 默认下载 480p 左右画质，已经尽量省流量和 token。

---

Credits & License

• Upstream project: mario-andreschak/mcp_video_recognition — original image/audio/video recognition MCP server.
• This fork only adds URL download / cookie / quality-selection features on top.
• Licensed under the MIT License (see LICENSE). The original copyright Copyright (c) 2025 mario-andreschak is retained.