doomscroll-mcp
The doomscroll-mcp server lets AI agents browse, search, and extract structured metadata from Instagram Reels for content research and trend analysis.
Authentication & Session Management
login()— Open a visible browser to sign in manually (only the browser profile is persisted, not credentials)login_status()— Check if the current session is still activelogout()— Clear the persisted browser profiledoctor()— Diagnose setup: verify browser, profile path, and auth state
Reel Discovery
scroll_reels(limit, mode)— Scroll the default Instagram Reels feedsearch_reels(query, limit, mode)— Search by keyword (includes view counts)hashtag_reels(tag, limit, mode)— Browse a specific hashtag page
Extracted Metadata (per reel)
URL, creator username, caption, visual description (IG alt-text)
Likes, comments, views, shares/reposts
Date posted (ISO 8601 & Unix timestamp)
Audio information and source metadata
Filtering & Sorting
Filter by recency (
posted_within_hours), engagement (min_views,min_likes,min_reposts), and caption keywords (contains)Sort and retrieve top reels by views, likes, reposts, or recent activity
Browsing Modes & Humanization
fast_test,normal_passive, andconservativemodes to control delay behavior and rate-limit riskRandomized delays, scroll jitter, and watch pauses to simulate human behavior
Session Persistence — Browser profile is saved locally so login is only required once across multiple runs.
Allows AI agents to browse Instagram Reels, search by keyword or hashtag, scroll through reels, and extract metadata such as URL, creator, caption, likes, comments, shares, audio, and date posted. The server interacts with Instagram Web via Playwright to collect structured reel data for content research.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@doomscroll-mcp Find reels about yoga"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
DoomScroll MCP
An MCP server that allows AI agents to browse Instagram Reels and perform content research.
Instead of manually scrolling through Instagram, agents can discover, inspect, filter, and analyze reels directly from the feed.
⚠️ Use at your own risk. Automating Instagram violates its Terms of Service and may get an account rate-limited, locked, or banned. Use a secondary / throwaway account — never your main account.
Features
Login to Instagram once
Persist browser session between runs
Browse the default Reels feed based on your algorithm
Search by keyword
Search by hashtag
Scroll through reels
Extract reel metadata
Filter and rank content before sending it to an AI model
Humanized browsing (randomized delays, scroll jitter, watch pauses)
Optional, opt-in account interactions (e.g. likes)
Related MCP server: reelminner
Extracted Data
For each reel, DoomScroll MCP attempts to collect:
Reel URL
Creator username
Caption / description
Audio information
Likes
Comments
Shares / reposts (when available)
Date posted
Note:
viewsis always null — Instagram does not expose reel view counts on the web (why).
The MCP returns structured data so the AI agent can decide what is interesting and what should be ignored.
Architecture
AI Agent
↓
DoomScroll MCP
↓
Playwright
↓
Instagram WebTechnology
Python
MCP
Playwright
uv
uv is used for fast dependency management and execution.
Session Persistence
Instagram login is only required once.
The Playwright browser profile is persisted locally and reused between runs.
First Run
---------
login()
→ User signs in
→ Session saved
Second Run
----------
login_status()
→ Logged In
No additional login required.MVP Scope
1. Login
login()
login_status()
logout()2. Scroll
scroll_reels(limit=50)Supports:
Default Reels feed
Search results
Hashtag pages
Examples:
scroll_reels()
scroll_reels(
search="yoga"
)
scroll_reels(
hashtag="yoga"
)3. Return Results
[
{
"url": "...",
"creator": "...",
"caption": "...",
"likes": 12345,
"comments": 123,
"date_posted": "...",
"audio": "...",
}
]The MCP does not perform analysis.
Its job is to collect and return reel data.
The AI agent is responsible for:
Trend detection
Content analysis
Ranking
Content recommendations
Content generation
Example Workflow
User:
Find content ideas for beginner yoga.
Agent:
→ login_status()
Agent:
→ scroll_reels(
search="beginner yoga",
limit=100
)
MCP:
→ Returns reel metadata
Agent:
→ Filters high-engagement reels
→ Analyzes hooks and formats
→ Returns top content ideasInstall
Requires uv. Two one-time setup steps before any
agent can use it:
# 1. Install the headless browser (shared cache, done once per machine)
uvx --from doomscroll-mcp playwright install chromium
# 2. Log in to Instagram by hand (opens a visible browser; no credentials stored)
uvx --from doomscroll-mcp doomscroll-loginFrom a git clone instead of PyPI, swap
uvx --from doomscroll-mcpforuv run --directory /path/to/doomscroll-mcp.
Then add it to your agent. The server speaks MCP over stdio.
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) /
%APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"doomscroll": {
"command": "uvx",
"args": ["doomscroll-mcp"]
}
}
}Claude Code
claude mcp add doomscroll -- uvx doomscroll-mcpCursor
~/.cursor/mcp.json (or any MCP client using the standard schema):
{
"mcpServers": {
"doomscroll": {
"command": "uvx",
"args": ["doomscroll-mcp"]
}
}
}From a local clone (no PyPI)
{
"mcpServers": {
"doomscroll": {
"command": "uv",
"args": ["run", "--directory", "/path/to/doomscroll-mcp", "doomscroll-mcp"]
}
}
}After it's wired up, have the agent call doctor() to confirm it sees your
logged-in profile. If login_status() ever reports logged out (expired session
or a checkpoint), run doomscroll-login again.
Tools
login(force=False)— headful sign-in, persist profilelogin_status()— is the session logged in?logout()— clear the profiledoctor()— browser/profile/auth diagnostics + next actionscroll_reels(limit=50, sort_by=None, top=None, mode=None)— feed, stop at a reel countdoomscroll(duration_seconds, sort_by=None, top=None, mode=None)— feed, stop after a wall-clock timesearch_reels(query, limit=50, sort_by=None, top=None, mode=None)— keyword search → matching reelshashtag_reels(tag, limit=50, sort_by=None, top=None, mode=None)— hashtag → matching reels
search_reels / hashtag_reels hit Instagram's top_serp search API directly
(relevance-filtered, paginated), not the explore UI.
doomscroll scrolls for a fixed time instead of a fixed count — e.g.
doomscroll(600) doomscrolls for 10 minutes. Add sort_by="views" + top=10
to get "the best reels from N minutes of scrolling". Duration is clamped to
DOOMSCROLL_MAX_DURATION_S (default 30 min). sort_by ∈
views | likes | reposts | recent (descending; None = discovery order).
Responses include stopped_reason (limit | duration | dry | capped).
Filters
All four collection tools accept filters, applied after collection, before sort/top:
posted_within_hours— recency window (e.g.24= last day)min_views/min_likes/min_reposts— engagement floors ("viral")contains— caption keyword, case-insensitive
Example — "best fresh reels from 10 minutes of doomscrolling":
doomscroll(600, posted_within_hours=24, sort_by="likes", top=10).
Responses include filtered_out (how many were dropped) and echo the active
filters. An empty result purely because filters excluded everything is a valid
response (reels: []), not an error.
Notes:
The feed's
viewsare null — usemin_likeson the feed,min_viewson search/hashtag.The home feed mixes fresh and evergreen reels, so a tight
posted_within_hoursreturns only the fresh minority (a longerdoomscrollcatches more).containsis keyword matching, not topic understanding. For real topic relevance usesearch_reels(Instagram's own ranking); semantic topic is the agent's job, not the server's.
Errors come back as structured dicts (code, retry_after, requires_headful,
suggested_tool) so an agent can recover instead of stalling.
See docs/sample-output.md for a real scroll_reels
run against the live feed.
Vision
Turn Instagram into a structured data source for AI-powered content research.
Login once. Scroll automatically. Return structured reel data. Let the AI decide what matters.
Available Tools
7 toolsdoctorA
Diagnose setup: browser availability, profile path, auth state, next action.
Inputs: no named parameters. Returns: object
hashtag_reelsB
Browse a hashtag page and return its reels.
tag with or without a leading '#'. Same reel shape and errors as
scroll_reels, sourced from instagram.com/explore/tags//.
Inputs: tag (required), mode, limit. Returns: object
loginA
Open a visible browser so you can sign in to Instagram by hand.
Credentials are never stored — only the browser profile is persisted, so you log in once. Use force=True to re-auth an expired session or clear a checkpoint. WARNING: automating Instagram violates its ToS and risks the account. Use a secondary/throwaway account, never your main.
Inputs: force. Returns: object
login_statusA
Report whether the persisted Instagram session is currently logged in.
Inputs: no named parameters. Returns: object
logoutA
Clear the persisted browser profile. Next run requires login() again.
Inputs: no named parameters. Returns: object
scroll_reelsA
Scroll the default Instagram Reels feed and return structured reel metadata.
Returns {reels: [...], count, timing, fill_rate}. Each reel: url, creator, caption, description (= caption), visual_description (IG auto alt-text), likes, comments, views, shares, reposts, date_posted (ISO 8601), date_posted_ts (unix), audio, _source. Engagement fields are best-effort — missing ones come back null rather than failing.
Note on views: the home feed omits view/play counts, so views is null here.
Use search_reels/hashtag_reels for reels WITH view counts. See
docs/views-investigation.md. shares and reposts are the same metric.
mode (optional): one of fast_test, normal_passive, conservative. Controls
humanized delay/cap. Defaults to the server's configured mode.
This call drives the default feed only. For a topic use search_reels;
for a tag use hashtag_reels.
Inputs: mode, limit. Returns: object
search_reelsA
Search Instagram by keyword and return matching reels.
Same reel shape and error handling as scroll_reels, sourced from the explore
search results for query (e.g. "beginner yoga"). Unlike the feed, search
results DO include views (play counts). comments is not in this payload
(comes back null).
Inputs: query (required), mode, limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: authentication (login, login_status, logout), setup diagnostics (doctor), and three different reels retrieval methods (scroll_reels for default feed, search_reels for keyword search, hashtag_reels for hashtag browsing). Descriptions explicitly note differences in view count availability, preventing confusion.
Tool names mix patterns: 'doctor' is a noun not following verb_noun, 'hashtag_reels' is noun_noun, while 'scroll_reels' and 'search_reels' are verb_noun. 'login', 'login_status', 'logout' are verb-based but not consistent with the others. The inconsistency makes naming less predictable.
Seven tools is well-scoped for an Instagram reels browsing server: three for authentication lifecycle, three for reels retrieval (feed, search, hashtag), and one for diagnostics. Each tool serves a clear function without redundancy.
The tool surface covers all essential operations for browsing Instagram reels: authentication setup, status checks, logout, and three distinct retrieval paths. Given the warning against automation beyond ToS, omitting write actions (like, comment) is appropriate. No obvious gaps for the stated purpose.
Maintenance
Related MCP Connectors
Search trending Instagram Reels and run AI video analysis via Writelo
Instagram for AI agents: publish, read comments and DMs, insights, and engage from your account.
Public Instagram reels, posts, profiles and comments, plus reel-to-text transcripts. No login.
Public Instagram and YouTube data for AI agents: reels, videos, channels, comments. Pay per result.
Related MCP Servers
- AlicenseAqualityFmaintenanceEnables AI assistants to interact with Instagram by scraping profiles, posts, reels, DMs, and business insights through a robust, DOM-agnostic browser orchestration engine that bypasses Instagram's anti-automation measures.281Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to scrape Instagram Reels and public profile data (metadata, engagement, owner info) without the official API, via tools for scraping, status checks, cookie import, stopping, and exporting results.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to transcribe Instagram Reels into text by providing a tool that accepts a Reel URL and returns the speech transcript along with metadata such as author and duration.MIT
- AlicenseAqualityCmaintenanceEnables AI agents to read public Instagram Reels without logging in, returning details, on-device timestamped speech-to-text transcripts, real video frames, preview comments, and Reel links harvested from web pages.32MIT