scrolller-mcp-cli-api

3-in-1 toolkit for Scrolller (unofficial): 🤖 MCP server for AI agents · ⌨️ terminal CLI · 📚 API clients (TypeScript + Python)

README на русском · Donate 💖

Scrolller hosts both regular (SFW) and NSFW media — NSFW is opt-in everywhere in this toolkit (default SFW).

⚠️ Unofficial project. Not affiliated with Scrolller. Built by reverse-engineering the site's public web client (protocol reference). Authenticated actions require your own Scrolller account. Respect the site's usage terms (~1 request/sec pacing is a good habit), content ratings and your local law. Some categories are 18+.

Features

• 🔍 Discovery — trending/random feeds, sorting (random / top / hot / new / controversial), media-type filters (photos / videos / videos with sound), categories

• 🔎 Search — subreddits (with live preview), users

• 📄 Posts — metadata, best media source picking, albums, related ("More like this")

• 💬 Comments — read (with replies), write, reply, like/unlike, delete, report

• ❤️ Likes & reposts, 👥 follow/unfollow subreddits and users, following feeds

• 📁 Collections — create/edit/delete, add/remove posts, paid collections

• 🔐 Auth — login(username|email, password) stores the token (+expiry); or paste a token manually

• 🔔 Notifications & ✉️ messages (conversations, threads, send, unread count)

• 📤 Upload media / create posts (auth), 📊 creator revenue reports (read-only)

• ⬇️ Downloads — original-quality videos (MP4/WEBM) and images, bulk by query, concurrency, progress, no-overwrite naming

• 🌐 Official agent routes — embed-safe JSON (/agent/*, no raw media URLs) for attribution-correct integrations

• 🛡️ Proxy support — http / https / socks4 / socks5 (socks4 via the Node client), interactive wizard, env/CLI overrides

• ⚙️ Shared config — one config.json + env vars for CLI and MCP; custom User-Agent and extra headers

• 🔞 NSFW opt-in — SFW (default) / NSFW / ALL on every read operation

Related MCP server: Mfuns MCP Server

Install

Node.js ≥ 22.19 required (CLI + MCP + TS library).

Option 1 — install from GitHub (works right now)

git clone https://github.com/LegitAntiAA/scrolller-mcp-cli-api
cd scrolller-mcp-cli-api

npm ci && npm run build          # build all Node packages

npm link -w scrolller-cli        # now `scrolller` works in any terminal
npm link -w scrolller-mcp        # now `scrolller-mcp` works (MCP clients run it)

scrolller --help                 # 🎉

npm link creates global commands pointing at your local build — re-run npm run build after pulling updates. The Python library is optional:

pip install -e python            # Python ≥ 3.9 (add "python[dev]" for tests)

Option 2 — install from the npm registry (once published)

npm install -g scrolller-cli downloads the package from the npm registry, not GitHub — these commands work after the packages are published there:

npm install -g scrolller-cli     # CLI
npm install -g scrolller-mcp     # MCP server
npm install scrolller-core       # TypeScript library
pip install scrolller-py         # Python ≥ 3.9 library

CLI quickstart

scrolller discover --limit 10               # trending feed
scrolller discover --sort top --videos      # filters: --photos --videos --with-sound --sort
scrolller search "burger" --limit 20        # search subreddits
scrolller subreddit aww --limit 30          # subreddit feed
scrolller post <post-url>                   # post details
scrolller comments <post-url>               # read comments

# downloads
scrolller download <post-url>               # one post, original quality
scrolller download "burger" -n 10 -o ./dl   # 10 items by query
scrolller download <post-url> -c 8          # 8 parallel workers

# auth (required for likes/comments/collections/etc.)
scrolller login                             # interactive: username + password
scrolller token <token>                     # or paste a token manually
scrolller whoami

# authenticated actions
scrolller like <post-url>
scrolller comment <post-url> "cool!"
scrolller collection create "My pack"
scrolller collection add <collection-id> <post-url>

# misc
scrolller agent subreddit carporn           # official embed-safe agent route
scrolller proxy                             # interactive proxy wizard (test included)
scrolller config get --json
scrolller donate                            # 💖 crypto addresses

Global flags: --json (machine output, no banner), --no-banner, --nsfw NSFW, --user-agent <ua>, --header "K: V" (repeatable), --proxy <url>, --timeout <ms>.

TypeScript library

import { ScrolllerClient } from "scrolller-core";

const client = new ScrolllerClient();

// paging generator (byte-exact cursors handled for you)
for await (const page of client.discoverPages({ limit: 10, nsfw: "SFW" })) {
  for (const sub of page.items) console.log(sub.title);
}

const post = await client.getPost("https://scrolller.com/some-post-abc123");
await client.download(post, "./out");            // original quality
await client.login("username", "password");      // token persisted to config
await client.like("https://scrolller.com/some-post-abc123");
await client.addComment("https://scrolller.com/some-post-abc123", "cool!");

Python library

from scrolller import ScrolllerClient

client = ScrolllerClient()                # async: AsyncScrolllerClient

for page in client.discover_pages(limit=10):
    for sub in page.items:
        print(sub.title)

post = client.get_post("https://scrolller.com/some-post-abc123")
client.download(post, "./out")
client.login("username", "password")      # token persisted
client.like("https://scrolller.com/some-post-abc123")

MCP server

Everything the CLI can do is exposed as MCP tools (scrolller-mcp, stdio): discover, search_media, subreddit_feed, search_subreddits, get_post, read_comments, add_comment, reply_comment, like_comment, delete_comment, like_post, unlike_post, repost_post, unrepost_post, follow, unfollow, list_collections, get_collection, create_collection, add_to_collection, remove_from_collection, edit_collection, delete_collection, whoami, login, set_token, logout, get_notifications, mark_notifications, get_conversations, get_messages, send_message, get_user, resolve_link, get_related, hide_post, unhide_post, get_hide_rules, report_post, download_media, agent_subreddit, agent_content, agent_collection, configure_proxy, clear_proxy, get_config, update_config.

Claude Desktop

Claude Desktop → Settings → Developer → Edit Config (or claude_desktop_config.json):

Installed from source via npm link? Use "command": "scrolller-mcp" (global command) instead of npx — and re-run npm run build after updates.

{
  "mcpServers": {
    "scrolller": {
      "command": "npx",
      "args": ["-y", "scrolller-mcp"],
      "env": { "SCROLLLER_NSFW": "SFW" }
    }
  }
}

Cursor

Cursor → Settings → MCP & Integrations → MCP Tools → New MCP Server, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "scrolller": {
      "command": "npx",
      "args": ["-y", "scrolller-mcp"]
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.scrolller]
command = "npx"
args = ["-y", "scrolller-mcp"]

Environment variables (work for CLI and MCP)

SCROLLLER_TOKEN, SCROLLLER_NSFW, SCROLLLER_USER_AGENT, SCROLLLER_EXTRA_HEADERS (JSON), SCROLLLER_PROXY (type://[user:pass@]host:port), SCROLLLER_DOWNLOAD_DIR.

Example agent session

Tell your agent:

"Here is my proxy (host, port, type) — configure it in Scrolller and log in with my credentials, then find and download 10 videos for the query burger, like the first 5, and comment cool on the first one."

The agent can do exactly that with configure_proxy → login → search_media/download_media ×10 → like_post ×5 → add_comment. Auth-required tools fail with a hint to login/set_token first, so agents self-correct.

Configuration

Shared config: %USERPROFILE%/.config/scrolller/config.json (Windows) / ~/.config/scrolller/config.json:

{
  "token": null,
  "expires_at": null,
  "nsfw": "SFW",
  "user_agent": null,
  "extra_headers": {},
  "proxy": { "type": "http", "host": "", "port": 0, "username": null, "password": null },
  "download_dir": "~/Downloads/scrolller",
  "timeout_ms": 30000
}

Precedence: explicit option → env → config file → defaults. The token is stored in plaintext (file is chmod 600 on POSIX) — treat it like a password.

Manual token: log in at scrolller.com in your browser, then copy the token from DevTools → Application → Local Storage → SCROLLLER_BETA_1:SCROLLLER_LOGIN_DEV.

Notes & limits

• Honest caveat: authenticated operations (likes, comments, collections, messages, …) are implemented from the site's verified GraphQL shapes but were not live-tested with a real account during development — public (no-auth) operations are fully live-verified.

• The site has no leaderboard / search-collections / global post-search GraphQL in its current web build (the UI leaderboard page has no public API), so those are not implemented; the official /agent/collection/{id} route covers collection lookup.

• register, password reset and payments are captcha-protected on the server — create accounts on the site, then scrolller login.

• searchCollections has no public GraphQL document in the current web build (official /agent/collection/{id} route works).

• Audio lives inside MP4/WEBM — no separate audio streams exist.

• Rate limits are per-IP; keep ~1 req/s for agent routes and be gentle with the GraphQL endpoint.

• socks4 proxies are supported by the Node client; the Python client supports http/https/socks5.

Repository layout

packages/core    → scrolller-core  (TypeScript client: transport + all operations)
packages/cli     → scrolller-cli   (terminal CLI, colored ASCII banner)
packages/mcp     → scrolller-mcp   (MCP server, stdio)
python/          → scrolller-py    (Python client: sync + async)
docs/api         → CONTRACT (canonical surface) + T1-RESEARCH-FULL (protocol reference)

💖 Donate

If this project saved you time, consider supporting development:

In the CLI: scrolller donate prints everything nicely colored. Thank you! 🙏

License

MIT — see LICENSE.