Skip to main content
Glama

DoomScroll MCP

CI PyPI Python License: MIT

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: 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.

Available Tools

7 tools
doctorA

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

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Enables 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.
      28
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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