Skip to content
Back to search

instagram-scraper

MarketplaceWorks with Claude CodeGitHub

Give Claude eyes and ears on Instagram: a read-only Claude Code plugin for posts, reels, profiles and comments, with local video analysis (OCR + transcript + scene map).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/doughrun--instagram-scraper/badge.svg)](/listings/doughrun--instagram-scraper)

HTML

<a href="/listings/doughrun--instagram-scraper"><img src="/api/listings/doughrun--instagram-scraper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

1. Install the prerequisites

<details open> <summary><b>Windows</b></summary>

winget install --id=astral-sh.uv -e
winget install --id=Gyan.FFmpeg -e

</details>

<details> <summary><b>macOS</b></summary>

brew install uv ffmpeg

</details>

<details> <summary><b>Linux (Debian/Ubuntu)</b></summary>

curl -LsSf https://astral.sh/uv/install.sh | sh
sudo apt install ffmpeg

</details>

Open a new terminal afterwards so `uv` and `ffmpeg` are on your `PATH`.

2. Install the plugin in Claude Code

Inside Claude Code:

/plugin marketplace add doughrun/instagram-scraper
/plugin install instagram-scraper@instagram-scraper

Then start a new Claude Code session so the skill loads.

3. First run: log in once

Ask Claude something like *"set up the Instagram scraper"*, or just paste an Instagram link. Claude will:

1. Check that `uv` and `ffmpeg` are available. 2. Ask whether you want the **GPU pack** (NVIDIA only) and whether it may add a **read permission** for the plugin's data folder, so it can view frames without a prompt for each image. 3. Open a **browser window once** so you can log in to Instagram normally (2FA and "is this you?" checks work, because it's a real browser). The window closes by itself when you're in.

From then on everything runs hidden. The session can last for months, until Instagram ends it.

> **Login window not working?** Run this yourself (the `!` prefix runs it in your Claude Code prompt) > and paste your `sessionid` cookie when asked. The input is hidden and never passes through Claude: > ```text > ! uv run "<plugin-dir>/skills/instagram-scraper/scripts/ig.py" login --paste > ```

Updating & uninstalling

/plugin marketplace update instagram-scraper
/plugin uninstall instagram-scraper@instagram-scraper

To remove your local data and login session, delete the data folder ([locations below](#where-your-data-lives)).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines
  1. {
  2. "name": "instagram-scraper",
  3. "owner": {
  4. "name": "doughrun",
  5. "url": "https://github.com/doughrun"
  6. },
  7. "metadata": {
  8. "description": "Instagram Scraper: read-only Instagram access for Claude Code — posts, reels, profiles, comments, and local video analysis."
  9. },
  10. "plugins": [
  11. {
  12. "name": "instagram-scraper",
  13. "source": "./plugins/instagram-scraper",
  14. "description": "Read-only Instagram for Claude: posts, reels, carousels, profiles, comments, media download, and token-efficient local video analysis (scene map, OCR, transcript, contact sheets, zoom).",
  15. "version": "0.1.0",
  16. "category": "research"
  17. }
  18. ]
  19. }
README.md · README · 349 lines
  1. <div align="center">
  2. <img src="plugins/instagram-scraper/.claude-plugin/icon.png" alt="Instagram Scraper icon" width="112" />
  3. # Instagram Scraper
  4. **Give Claude eyes and ears on Instagram.**
  5. A read-only [Claude Code](https://code.claude.com) plugin that fetches posts, reels, carousels, profiles and comments, and turns videos into something Claude can actually *watch and hear*, locally and at a fraction of the token cost.
  6. [![CI](https://github.com/doughrun/instagram-scraper/actions/workflows/ci.yml/badge.svg)](https://github.com/doughrun/instagram-scraper/actions/workflows/ci.yml)
  7. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  8. [![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-6b4fbb)](https://code.claude.com/docs/en/plugins)
  9. [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776ab)](https://www.python.org)
  10. [![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)](#requirements)
  11. [Install](#installation) · [What you can ask](#what-you-can-ask) · [How it works](#how-it-works) · [Commands](#command-reference) · [Privacy & safety](#privacy--safety) · [Troubleshooting](#troubleshooting) · [Contributing](CONTRIBUTING.md)
  12. </div>
  13. ---
  14. ## Why
  15. Ask Claude about an Instagram reel today and it hits a wall. Browser automation can see a page, but it
  16. can't hear the audio or follow a video, and logged-out Instagram hides most of what matters.
  17. **Instagram Scraper** closes that gap:
  18. - **Every layer of a post:** caption, hashtags, mentions, tagged accounts, audio track, likes,
  19. comments *with replies*, location, paid-partnership flag, alt text, and the original photos and videos.
  20. - **Video Claude can understand:** a local pipeline splits the video into scenes, reads every bit of
  21. on-screen text (OCR at 5 fps), transcribes the speech (Whisper), and packs it all into a short text
  22. **video map** plus a contact sheet. Claude reads that instead of thousands of frames.
  23. - **Fully local processing:** OCR, transcription and frame analysis run on your machine. No
  24. third-party scraping APIs and no cloud transcription.
  25. - **Automatic:** once installed, Claude uses it whenever a conversation involves Instagram. Paste
  26. a link and ask your question.
  27. ## What you can ask
  28. ```text
  29. What is she saying in this reel? My Spanish isn't great. https://www.instagram.com/reel/…
  30. Look at @some.creator. What do they post about, what performs best, and have they done paid partnerships?
  31. Summarize the comments on this post. Are people actually happy with the product? https://www.instagram.com/p/…
  32. Is the vacuum at around 0:12 in this video a real Dyson or a knockoff? https://www.instagram.com/reel/…
  33. Write down the recipe from this cooking reel, including the quantities he says out loud.
  34. ```
  35. Claude decides which steps it needs: fetch the post, read the video map, glance at a contact sheet,
  36. zoom into one frame. You don't have to name the plugin or any command.
  37. ### What Claude actually sees
  38. <img src="assets/what-claude-sees.png" alt="Left: all 150 frames of a 15-second reel, about 67,000 image tokens. Right: what Instagram Scraper gives Claude instead: one contact sheet and a short text map of on-screen text and speech, about 1,600 tokens." />
  39. ## How it works
  40. ```mermaid
  41. flowchart LR
  42. A["Instagram link<br/>or @handle"] --> B["Hidden browser<br/>(your logged-in session)"]
  43. B -->|"reads the page's own data"| C["post.json<br/>caption · comments · stats"]
  44. B --> D["Photos & videos<br/>(downloaded locally)"]
  45. D --> E["10 fps scan → scene segments"]
  46. E --> F["Local OCR<br/>on-screen text"]
  47. D --> G["Local Whisper<br/>transcript"]
  48. E --> H["Contact sheet(s)"]
  49. F --> I["video_map.md"]
  50. G --> I
  51. H --> J(("Claude"))
  52. I --> J
  53. C --> J
  54. J -.->|"only if needed"| K["Zoom: full-res crop<br/>or every frame in a range"]
  55. ```
  56. 1. **Fetching.** A hidden browser on your own logged-in profile opens the page like a normal visit, and
  57. the plugin reads the data Instagram sends to that page. It **never calls Instagram's private APIs
  58. directly**. That's both gentler on your account and more robust to endpoint changes.
  59. 2. **Video map, then zoom.** Instead of sending Claude every frame, the plugin makes everything
  60. that's cheap to detect into text:
  61. ```markdown
  62. # Video map — reel.mp4
  63. duration 15.0s · 1080x1920 · 10 segments · audio: yes · speech lang: en
  64. Contact sheets: sheet_01.jpg (~1036 tok)
  65. - #2 [00:00.4–00:03.0] · speech: "Here are three mistakes beginners make with reef tanks."
  66. - #6 [00:05.0–00:06.5] · text: "CODE REEF50" | "Mistake 1: no water change" · speech: "First, skipping water changes."
  67. - #10 [00:10.0–00:15.0] · text: "ACME" | "Follow for part 2" · speech: "Follow for part two."
  68. ```
  69. Claude reads the map, looks at one contact sheet, and zooms only where the question points.
  70. Above, a promo code that was on screen for **0.3 s** and a tiny corner logo were both caught by OCR
  71. without Claude viewing a single frame.
  72. <table>
  73. <tr>
  74. <td width="40%"><img src="assets/demo-contact-sheet.jpg" alt="Contact sheet: one tile per scene" /></td>
  75. <td valign="top">
  76. **Contact sheet**: one labeled tile per scene, about 1,000 tokens for the whole video.
  77. **Range zoom**: every frame between two timestamps, when something happens fast:
  78. <img src="assets/demo-range-zoom.jpg" alt="Range zoom around a 0.3-second flash" width="320" />
  79. **Crop zoom**: a full-resolution crop for fine detail, about 100 tokens:
  80. <img src="assets/demo-zoom-crop.jpg" alt="Full-resolution crop of a small logo" width="220" />
  81. </td>
  82. </tr>
  83. </table>
  84. <sub>Demo images come from a synthetic test video generated for this repo.</sub>
  85. ### Token cost (30-second reel)
  86. | Approach | Tokens Claude spends on images | Catches 0.3 s on-screen text? |
  87. |---|---|---|
  88. | Every frame at 10 fps | ~135,000 | yes |
  89. | 40 evenly spaced key frames | ~18,000 | often misses it |
  90. | **Video map + contact sheet (this plugin)** | **~1,000–2,500** | **yes, via OCR** |
  91. Need more? Claude can zoom into any moment, or run `thorough` mode (every scene at full resolution),
  92. which states its token cost and asks first.
  93. ## Requirements
  94. | | |
  95. |---|---|
  96. | **Claude Code** | Recent version with plugin support |
  97. | **[uv](https://docs.astral.sh/uv/)** | Runs the scripts and installs Python dependencies automatically, with no virtualenv to manage |
  98. | **[ffmpeg](https://ffmpeg.org)** | Video decoding (`ffmpeg` and `ffprobe` on your `PATH`) |
  99. | **Microsoft Edge or Google Chrome** | Used as the hidden browser. If neither is installed, Playwright's Chromium works too |
  100. | **An Instagram account** | A **secondary account is strongly recommended** (see [Privacy & safety](#privacy--safety)) |
  101. | **Optional: NVIDIA GPU** | Faster, more accurate transcription (opt-in, ~1 GB download) |
  102. **Platform status:** Windows 11 is tested end to end. macOS is being tested now. Linux should work
  103. but is untested; reports are welcome.
  104. ## Installation
  105. ### 1. Install the prerequisites
  106. <details open>
  107. <summary><b>Windows</b></summary>
  108. ```powershell
  109. winget install --id=astral-sh.uv -e
  110. winget install --id=Gyan.FFmpeg -e
  111. ```
  112. </details>
  113. <details>
  114. <summary><b>macOS</b></summary>
  115. ```bash
  116. brew install uv ffmpeg
  117. ```
  118. </details>
  119. <details>
  120. <summary><b>Linux (Debian/Ubuntu)</b></summary>
  121. ```bash
  122. curl -LsSf https://astral.sh/uv/install.sh | sh
  123. sudo apt install ffmpeg
  124. ```
  125. </details>
  126. Open a new terminal afterwards so `uv` and `ffmpeg` are on your `PATH`.
  127. ### 2. Install the plugin in Claude Code
  128. Inside Claude Code:
  129. ```text
  130. /plugin marketplace add doughrun/instagram-scraper
  131. /plugin install instagram-scraper@instagram-scraper
  132. ```
  133. Then start a new Claude Code session so the skill loads.
  134. ### 3. First run: log in once
  135. Ask Claude something like *"set up the Instagram scraper"*, or just paste an Instagram link. Claude will:
  136. 1. Check that `uv` and `ffmpeg` are available.
  137. 2. Ask whether you want the **GPU pack** (NVIDIA only) and whether it may add a **read permission**
  138. for the plugin's data folder, so it can view frames without a prompt for each image.
  139. 3. Open a **browser window once** so you can log in to Instagram normally (2FA and "is this you?"
  140. checks work, because it's a real browser). The window closes by itself when you're in.
  141. From then on everything runs hidden. The session can last for months, until Instagram ends it.
  142. > **Login window not working?** Run this yourself (the `!` prefix runs it in your Claude Code prompt)
  143. > and paste your `sessionid` cookie when asked. The input is hidden and never passes through Claude:
  144. > ```text
  145. > ! uv run "<plugin-dir>/skills/instagram-scraper/scripts/ig.py" login --paste
  146. > ```
  147. ### Updating & uninstalling
  148. ```text
  149. /plugin marketplace update instagram-scraper
  150. /plugin uninstall instagram-scraper@instagram-scraper
  151. ```
  152. To remove your local data and login session, delete the data folder ([locations below](#where-your-data-lives)).
  153. ## Command reference
  154. Claude runs these for you. They're documented here for transparency and power users.
  155. Every command is `uv run <skill-dir>/scripts/ig.py <command>` and prints JSON.
  156. | Command | Description |
  157. |---|---|
  158. | `post <url-or-shortcode>` | Full pipeline for one post, reel or carousel: data, comments and replies, media download, video map for every video. `--max-comments N` (200), `--no-comments`, `--no-transcribe`, `--no-video`, `--refresh` |
  159. | `profile <user-or-url>` | Bio, stats, links, latest `--limit N` posts (12), plus a thumbnail contact sheet of the feed. `--deep` runs `post` on every post |
  160. | `comments <url-or-shortcode>` | Compact, offline view of a fetched post's comments. `--limit`, `--sort likes\|time`, `--grep REGEX`, `--no-replies` |
  161. | `zoom <video> --t T --region R` | Full-resolution crop at time T (`tl tr bl br top bottom left right center full`, or `--box x,y,w,h`) |
  162. | `zoom <video> --start A --end B` | Contact sheet of every frame in a time range |
  163. | `thorough <video> [--yes]` | Every scene at full resolution in quadrants. Estimates the token cost first |
  164. | `video <file>` / `transcribe <file>` | The video pipeline for any local video file |
  165. | `setup [--gpu] [--allow-read]` | Check prerequisites, log in if needed, optional extras |
  166. | `login [--paste]` · `status` | Session management. `status` shows which account is in use |
  167. **Exit codes:** `0` ok · `1` error · `2` bad input or not found · `3` not logged in or security check · `4` rate-limited.
  168. ### What a fetched post looks like
  169. ```text
  170. <data>/cache/posts/<shortcode>/
  171. ├── post.json # caption, hashtags, mentions, tags, audio, stats, comments + replies
  172. ├── media/01.mp4, 02.jpg # original files, carousel order
  173. └── analysis/01/
  174. ├── video_map.md # the text map Claude reads first
  175. ├── sheet_01.jpg # contact sheet(s)
  176. ├── transcript.txt # timestamped speech
  177. └── scan/ # 10 fps frames (for range zooms)
  178. ```
  179. ## Privacy & safety
  180. **Read this before you use it.**
  181. - **Read-only.** The plugin never likes, comments, follows, posts or sends messages.
  182. - **Your session stays on your machine.** The login lives only in a dedicated browser profile inside
  183. the plugin's data folder. Your password is never stored, and the plugin never touches your everyday
  184. browser.
  185. - **Processing is local.** Downloads, OCR, transcription and frame analysis run on your computer.
  186. **Images Claude looks at are sent to Anthropic** as part of your conversation, like any image you
  187. share with Claude.
  188. - **Use a secondary Instagram account.** Automated access is against Instagram's Terms of Use, and
  189. Instagram can restrict accounts it believes are automated. The plugin is designed to be gentle:
  190. normal page visits only, human-paced pauses, one browser at a time, no bulk mode, and it **stops
  191. immediately when Instagram signals rate limiting** rather than retrying. You are still responsible
  192. for how you use it.
  193. - **Respect people.** Comments and posts belong to their authors. Don't use this to harass, track or
  194. profile private individuals, and follow the laws that apply to you (e.g. GDPR).
  195. ### Where your data lives
  196. | OS | Data folder |
  197. |---|---|
  198. | Windows | `%LOCALAPPDATA%\instagram-scraper\` |
  199. | macOS | `~/Library/Application Support/instagram-scraper/` |
  200. | Linux | `~/.local/share/instagram-scraper/` |
  201. Set `IG_SKILL_DATA_DIR` to use a different folder.
  202. ## Performance
  203. Approximate times from test runs on Windows 11 (32-core CPU, RTX 3060 Ti):
  204. | Task | Time |
  205. |---|---|
  206. | Profile (12 posts + thumbnail sheet) | ~15 s |
  207. | Image post + 30 comments | ~25 s |
  208. | 18 s reel + 60 comments, full video map | ~90 s |
  209. | 43 s reel, video map only | ~80 s |
  210. OCR dominates video time and runs on the CPU, so a video takes roughly **1–2× its length** to
  211. analyze. Comments are read at a human pace, about 30 s per 200.
  212. ## Troubleshooting
  213. | Symptom | Fix |
  214. |---|---|
  215. | `session_expired` | Your Instagram session ended. Ask Claude to log in again, or run `setup`. |
  216. | `checkpoint` | Instagram wants a security check. Open Instagram in your browser or app, confirm it's you, then retry. |
  217. | `rate_limited` | Instagram is throttling the account. **Stop and wait a few hours.** Don't retry in a loop. |
  218. | `busy` | Another Instagram command is running. They run one at a time. |
  219. | `no_browser` | Install Edge or Chrome, or run `uv run --with playwright playwright install chromium`. |
  220. | `missing_prereqs` | Install `ffmpeg`/`uv` (see [Installation](#installation)) and open a new terminal. |
  221. | A permission prompt for every frame | Run `setup --allow-read`, or allow reads of the [data folder](#where-your-data-lives) in Claude Code. |
  222. | Transcription is slow | Run `gpu-setup` if you have an NVIDIA GPU. CPU transcription uses a smaller model. |
  223. ## FAQ
  224. **Is this an official Instagram or Meta product?**
  225. No. It isn't affiliated with, endorsed by, or sponsored by Meta or Instagram.
  226. **Why not use the official Instagram API?**
  227. The Graph API only covers business and creator accounts *you manage*. It can't read arbitrary public
  228. posts, reel audio, or comment threads on other accounts.
  229. **Why do view counts show as `null`?**
  230. Instagram only shows view counts to the account owner.
  231. **Why are there fewer replies than `reply_count`?**
  232. Instagram counts replies it hides (deleted or restricted), so it can't return all of them.
  233. **Does it work on private accounts?**
  234. Only accounts your logged-in account can already see. Otherwise you get the profile header only.
  235. **Can it download stories or highlights?**
  236. Not yet. See the roadmap.
  237. ## Roadmap
  238. - [ ] GPU-accelerated OCR (about 7× faster in early tests)
  239. - [ ] macOS and Linux verification in CI with a recorded fixture
  240. - [ ] Stories and highlights
  241. - [ ] Optional MCP server exposing the same tools
  242. - [ ] Hashtag and location pages
  243. Ideas and votes welcome in [Discussions](https://github.com/doughrun/instagram-scraper/discussions) and [Issues](https://github.com/doughrun/instagram-scraper/issues).
  244. ## Contributing
  245. Contributions are very welcome: bug reports, Instagram layout changes you've spotted, platform
  246. testing, docs. Start with [CONTRIBUTING.md](CONTRIBUTING.md). Everyone taking part is expected to
  247. follow the [Code of Conduct](CODE_OF_CONDUCT.md). Found a security issue? See [SECURITY.md](SECURITY.md).
  248. ## Acknowledgements
  249. Built with [Playwright](https://playwright.dev), [faster-whisper](https://github.com/SYSTRAN/faster-whisper),
  250. [RapidOCR](https://github.com/RapidAI/RapidOCR), [FFmpeg](https://ffmpeg.org), [Pillow](https://python-pillow.org),
  251. and [uv](https://github.com/astral-sh/uv).
  252. ## License
  253. [MIT](LICENSE) © 2026 doughrun
  254. <sub>Instagram is a trademark of Meta Platforms, Inc. This project is independent and not affiliated
  255. with Meta. Use it responsibly and in line with Instagram's Terms of Use and the laws that apply to you.</sub>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.