# vid-agent-mcp

> MCP server for video understanding — transcribe Bilibili videos, search, and analyze local files through natural conversation with Claude.

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

Chat with Claude and ask it to watch a video for you. Send a Bilibili link, get back a structured summary with key points, visual moments, and a "worth watching" verdict — all through MCP tools.

## How it works

```
You: "转录一下这个视频 BV1pzjy6GEkC"

Claude: *calls transcribe tool*
        → Downloads video via BBDown
        → Transcribes audio with faster-whisper
        → Identifies key visual moments via VLM
        → Returns structured summary

You: "最近有什么AI Agent新视频？"

Claude: *calls search_by_intent tool*
        → Expands intent into multiple search queries
        → Searches Bilibili concurrently
        → Merges & ranks results by popularity
```

## Tools

| Tool | Description |
|------|-------------|
| `transcribe` | Download + analyze a Bilibili video |
| `transcribe_local` | Analyze a local video file |
| `search` | Search Bilibili by keyword |
| `search_by_intent` | AI-powered search with natural language |
| `get_result` | Read a previously saved result |

## Setup

### Prerequisites

- Python 3.11+
- ffmpeg (install via `conda install ffmpeg` or system package manager)
- BBDown (for Bilibili downloads) — [install from here](https://github.com/nilaoda/BBDown) or use an existing install
- A [MiMo API key](https://platform.xiaomimimo.com) (or any OpenAI-compatible VLM API)

### Install

```bash
# 1. Clone
git clone https://github.com/ikerrrrrrrrrrr/bili-vid-agent
cd bili-vid-agent

# Or install the MCP server directly
pip install vid-agent-mcp

# 2. Configure
cp .env.example .env
# Edit .env with your API key

# 3. Run
vid-agent-mcp
```

### Claude Desktop configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "vid-agent": {
      "command": "vid-agent-mcp",
      "env": {
        "VLM_API_KEY": "your-key-here"
      }
    }
  }
}
```

Or point to a local install:

```json
{
  "mcpServers": {
    "vid-agent": {
      "command": "conda",
      "args": ["run", "-n", "vid_agent", "vid-agent-mcp"]
    }
  }
}
```

## Configuration

All config via `.env` file or environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `VLM_API_KEY` | — | MiMo API key (required) |
| `VLM_BASE_URL` | `https://api.xiaomimimo.com/v1` | API base URL |
| `VLM_MODEL` | `mimo-v2-omni` | Model for visual analysis |
| `SUMMARY_MODEL` | `mimo-v2.5-pro` | Model for summary generation |
| `BBDOWN_PATH` | `bbdown` | Path to BBDown binary |
| `WHISPER_MODEL` | `turbo` | Whisper model size |
| `CACHE_DIR` | `./cache` | Download/transcription cache |
| `WORK_DIR` | `./work` | Working directory |

## License

Apache 2.0