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)

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: views is 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 Web

Technology

• 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 ideas

Install

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-login

From a git clone instead of PyPI, swap uvx --from doomscroll-mcp for uv 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-mcp

Cursor

~/.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 profile
• login_status() — is the session logged in?
• logout() — clear the profile
• doctor() — browser/profile/auth diagnostics + next action
• scroll_reels(limit=50, sort_by=None, top=None, mode=None) — feed, stop at a reel count
• doomscroll(duration_seconds, sort_by=None, top=None, mode=None) — feed, stop after a wall-clock time
• search_reels(query, limit=50, sort_by=None, top=None, mode=None) — keyword search → matching reels
• hashtag_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 views are null — use min_likes on the feed, min_views on search/hashtag.
• The home feed mixes fresh and evergreen reels, so a tight posted_within_hours returns only the fresh minority (a longer doomscroll catches more).
• contains is keyword matching, not topic understanding. For real topic relevance use search_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.