# reelmint-local-mcp

A tiny **local MCP server** for Claude Desktop (and any MCP client) whose one job is
to **download a video on your own machine** — Instagram reels, YouTube, TikTok, or
any [yt-dlp](https://github.com/yt-dlp/yt-dlp)-supported URL — and hand back the
**saved file path** (plus a few preview keyframes).

Because it runs on **your** computer (a residential IP, optionally with your
logged-in browser cookies), it reaches content a *server* can't: platforms block
datacenter IPs, so a cloud service either fails or has to pay a proxy to fetch the
bytes. On your laptop, the download is free and just works.

> It does **only** the download. Understanding the video, transcripts, and building
> anything from it are done by whatever MCP/tools you hand the file to.
>
> Built for [ReelMint](https://reelmint.io) but depends on nothing from it — works
> with any MCP client.

## Tools

| Tool | What it does |
|---|---|
| `download_video(url, frames=6)` | Download a video to a local file → returns the **saved `.mp4` path** + a few keyframe images for a quick look. |
| `status()` | Reports whether yt-dlp / ffmpeg are installed + the active cookie/save config. |

## Requirements

- **Python 3.10+**
- **ffmpeg** — for the preview keyframes. macOS: `brew install ffmpeg` (downloads still work without it; you just won't get frames)

## Install

```bash
git clone https://github.com/HiteshR90/reelmint-local-mcp.git
cd reelmint-local-mcp
python3 -m venv .venv
.venv/bin/pip install -U pip -r requirements.txt

# sanity check (expect ready: True)
.venv/bin/python -c "import server; print(server.status())"
```

## Connect to Claude Desktop

Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`
(merge into your existing `mcpServers`), using **absolute paths**, then fully quit
and reopen Claude Desktop:

```json
{
  "mcpServers": {
    "reelmint-local": {
      "command": "/absolute/path/to/reelmint-local-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/reelmint-local-mcp/server.py"],
      "env": {
        "IG_COOKIES_FROM_BROWSER": "chrome",
        "IG_SAVE_DIR": "~/Downloads/reelmint-reels"
      }
    }
  }
}
```

Then just ask: *"download_video this <url>"* → you get the saved path (and a
preview). Drag that file into your MCP client to do anything else with it.

## Configuration (env)

| Var | Default | Meaning |
|---|---|---|
| `IG_COOKIES_FROM_BROWSER` | `chrome` | Browser to read cookies from (`chrome`/`safari`/`firefox`/`edge`/`brave`); `""` = public only. Unlocks private/followed content. |
| `IG_SAVE_DIR` | `~/Downloads/reelmint-reels` | Where downloads are saved. |
| `IG_MAX_FRAMES` | `8` | Hard cap on preview keyframes. |

## Notes & limits

- **Private accounts** need your browser cookies (`IG_COOKIES_FROM_BROWSER`) and that
  you follow the account. Reading cookies may prompt for OS keychain access; some
  browsers must be closed first.
- Platforms fight scrapers; keep it fresh with `pip install -U yt-dlp`.
- This is a client-side utility. You are responsible for complying with the terms of
  service of the sites you download from.

## License

[MIT](./LICENSE) — © 2026 Hitesh R (ReelMint).