---
name: vidcrawl
description: "Turn YouTube, TikTok, Instagram Reels, and X video URLs into LLM-ready timestamped Markdown, visual storyboard frames, on-screen OCR, and structured JSON via remote MCP, stdio MCP, CLI, or REST API."
---

# VidCrawl

VidCrawl gives AI agents structured video context from public YouTube (including Shorts), TikTok, Instagram Reels, and X video URLs.

## Progressive Disclosure Rules

1. Always start with Layer 1 (`vidcrawl_scrape` or `POST /v1/scrape`, 1 credit, 0 LLM tokens). It returns metadata, chapters, deduplicated timestamped transcript segments, a lightweight storyboard grid, and LLM-ready Markdown.
2. Never ingest a full raw video stream into a language model by default.
3. Use Layer 2A (`vidcrawl_frames` or `POST /v1/frames`, 1 credit) only when the transcript and storyboard leave ambiguity on a specific slide, code block, chart, or UI screen. Pass exact `timestamps_sec` (1 to 20 timestamps, `max_width` 320 to 1920).
4. Use Layer 2B (`vidcrawl_search` or `POST /v1/search`, 1 credit) to discover YouTube videos by topic, optionally setting `scrape: true` (+1 credit per scraped result).
5. Use Layer 3 (`vidcrawl_agent` or `POST /v1/agent`, 3/5/10 credits for `low`/`medium`/`high` effort) for bounded multi-step visual + spoken synthesis across 1 to 10 URLs with `[MM:SS]` citations and optional JSON `schema`.
6. Use `vidcrawl_account` or `GET /v1/account` (0 credits) to verify authentication and inspect remaining credits before batch runs.
7. Always cite `[MM:SS]` timestamps in your answers and distinguish spoken evidence from visual evidence.

## Remote Streamable HTTP MCP Setup

Endpoint: `https://vidcrawl.com/mcp` (also mounted at `https://vidcrawl.com/v1/mcp`). Authenticate with `Authorization: Bearer $VIDCRAWL_API_KEY` or `x-api-key: $VIDCRAWL_API_KEY`.

### Claude Code

```bash
claude mcp add --transport http vidcrawl https://vidcrawl.com/mcp \
  --header "Authorization: Bearer $VIDCRAWL_API_KEY"
```

### OpenAI Codex

```bash
codex mcp add vidcrawl --url https://vidcrawl.com/mcp
# In ~/.codex/config.toml under [mcp_servers.vidcrawl], set:
# bearer_token_env_var = "VIDCRAWL_API_KEY"
```

### Cursor / Windsurf / VS Code

Add to your MCP JSON configuration (`.cursor/mcp.json` or `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "vidcrawl": {
      "url": "https://vidcrawl.com/mcp",
      "headers": {
        "Authorization": "Bearer $VIDCRAWL_API_KEY"
      }
    }
  }
}
```

## Local Stdio MCP and CLI

Run the stdio MCP server or CLI with `VIDCRAWL_API_KEY` set (pointing to `https://vidcrawl.com`):

```bash
# Stdio MCP server
VIDCRAWL_API_KEY="$VIDCRAWL_API_KEY" VIDCRAWL_API_URL="https://vidcrawl.com" npx -y @vidcrawl/mcp mcp

# CLI commands
npx -y @vidcrawl/mcp scrape 'https://www.youtube.com/watch?v=1E3tv_3D95g'
npx -y @vidcrawl/mcp frames 'https://www.youtube.com/watch?v=1E3tv_3D95g' --at 150,365
npx -y @vidcrawl/mcp search 'MiniMax AI lab' --limit 5
npx -y @vidcrawl/mcp agent 'https://www.youtube.com/watch?v=1E3tv_3D95g' --prompt 'Summarize key changes' --effort low
```

## MCP Tools

- `vidcrawl_scrape` (1 credit): Extract metadata, chapters, timestamped transcript, storyboard sheets, and Markdown. Input: `{ url, lang? }`.
- `vidcrawl_frames` (1 credit): Extract up to 20 high-resolution JPEG frames at `timestamps_sec`. Input: `{ url, timestamps_sec, max_width? }`.
- `vidcrawl_search` (1 credit, +1 per scraped result): Search YouTube videos. Input: `{ query, limit?, scrape?, lang? }`.
- `vidcrawl_agent` (3/5/10 credits): Grounded video agent across 1 to 10 URLs. Input: `{ prompt, urls, effort?, schema? }`.
- `vidcrawl_account` (0 credits): Check remaining credit balance and endpoint credit prices. Input: `{}`.

## REST API Reference

Base URL: `https://vidcrawl.com`
Authentication header: `Authorization: Bearer <API_KEY>` or `x-api-key: <API_KEY>`.

- `POST /v1/scrape` (1 credit): Body `{ "url": "...", "formats"?: ["markdown", "segments", "storyboard"], "lang"?: "en" }`
- `POST /v1/frames` (1 credit): Body `{ "url": "...", "timestamps_sec": [150, 365], "max_width"?: 1280 }`
- `POST /v1/search` (1 credit): Body `{ "query": "...", "platform"?: "youtube", "limit"?: 5, "scrape"?: false, "lang"?: "en" }`
- `POST /v1/agent` (3/5/10 credits): Body `{ "prompt": "...", "urls": ["..."], "effort"?: "low" | "medium" | "high", "schema"?: { ... } }`
- `GET /v1/account` (0 credits): Returns `{ ok: true, user_id, credits, costs }`.

## Credits and Packs

- New accounts start with 100 free credits (no card required).
- Starter Pack: 1,000 credits for $9 (one-time, never expire).
- Growth Pack: 4,000 credits for $29 (one-time, never expire).

## Error Codes

Every error returns JSON `{ "ok": false, "error": { "code": "...", "message": "...", "request_id": "..." } }` and sets the `X-Request-Id` header.

- `UNAUTHORIZED` (401): Missing or invalid API key.
- `INSUFFICIENT_CREDITS` (402): Balance is below the required endpoint credits.
- `INVALID_JSON` (400): Request body is not valid JSON.
- `VALIDATION_ERROR` (400): Request fields failed contract validation (see `error.issues`).
- `PAYLOAD_TOO_LARGE` (413): Request body exceeded 65536 bytes.
- `INVALID_URL` / `UNSUPPORTED_PLATFORM`: URL is not a supported public YouTube, TikTok, Instagram Reel, or X video (or search on an unsupported platform).
- `VIDEO_UNAVAILABLE` (404): Video is private, deleted, or region-restricted.
- `NO_CAPTIONS_AVAILABLE`: No captions or spoken transcript could be extracted.
- `MEDIA_UNAVAILABLE`: Video media stream could not be accessed for frame slicing.
- `YOUTUBE_BOT_CHALLENGED`: Upstream provider challenged the request; retry later.
- `UPSTREAM_TIMEOUT` / `UPSTREAM_ERROR` (500/502): Upstream extraction or model failure.

## Discovery Links

- OpenAPI 3.1 JSON: `https://vidcrawl.com/docs/json`
- Interactive API Reference: `https://vidcrawl.com/api-reference`
- Markdown API Reference: `https://vidcrawl.com/api-reference.md`
- MCP Setup Guide: `https://vidcrawl.com/mcp` (`https://vidcrawl.com/mcp.md`)
- Compact Index: `https://vidcrawl.com/llms.txt`
- Complete Bundle: `https://vidcrawl.com/llms-full.txt`
