Mobbin Agent

MCP server that gives AI agents browser-based access to Mobbin for design research, screen discovery, and screenshot collection.

Claude Code (AI reasoning + decisions)
    ↕ MCP Protocol (stdio)
Mobbin Agent (TypeScript MCP server)
    ↕ Playwright (browser automation)
Mobbin.com (authenticated session)
    ↕ Local filesystem
data/downloads/ (saved screenshots)

The AI agent decides what to browse, search, and download. The MCP server provides deterministic browser control tools. No extra LLM cost per browser action.

Features

• 10 MCP tools — lifecycle, navigation, interaction, perception, collection
• Session persistence — authenticate once, sessions auto-restore across runs
• Structured extraction — page data returned as classified JSON (screens, flows, apps, categories)
• Full-resolution downloads — batch download screen images at 1920px PNG quality
• Anti-detection — realistic user agent, disabled automation flags, human-like delays
• Direct script access — bypass MCP and import modules directly for batch tasks

Requirements

• Node.js >= 18
• A Mobbin account (free or paid)

Setup

git clone git@github.com:ismailsaleekh/mobbin-agent.git
cd mobbin-agent
npm install
npx playwright install chromium
npm run build

First-time authentication

Mobbin requires login. On first use, authenticate in a visible browser window — the session is saved automatically for future runs.

node -e "
import('./dist/browser.js').then(async ({ BrowserManager }) => {
  const { MobbinNavigator } = await import('./dist/mobbin.js');
  const browser = new BrowserManager();
  await browser.launch({ headless: false });
  const mobbin = new MobbinNavigator(browser);
  const result = await mobbin.login();
  console.log(result);
  await browser.close();
  process.exit(0);
});
"

A Chromium window opens to mobbin.com/login. Log in manually — the server detects completion and saves cookies to data/session/storage-state.json. Sessions last ~24-48 hours.

Usage with Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "mobbin": {
      "command": "node",
      "args": ["/absolute/path/to/mobbin-agent/dist/index.js"]
    }
  }
}

Then ask Claude to browse Mobbin:

"Find trending dashboard screen patterns on Mobbin and download the top 20 at full resolution"

"Browse onboarding flows on Mobbin and extract the screen URLs for e-commerce apps"

Tools

10 tools across 5 categories:

Category	Tool	Description
Lifecycle	mobbin_connect	Launch browser and restore saved session
	mobbin_login	Navigate to login page for manual authentication
	mobbin_disconnect	Save session and close browser
Navigation	mobbin_navigate	Go to any Mobbin URL, wait for load
	mobbin_scroll	Scroll page to load more content (infinite scroll)
Interaction	mobbin_click	Click element by text, CSS selector, or coordinates
	mobbin_type	Type text into input field
Perception	mobbin_screenshot	Take viewport screenshot (returns PNG)
	mobbin_extract	Extract structured data from current page
Collection	mobbin_download	Download screen images by URL to local filesystem

See Tool Reference for parameters, return formats, and examples.

Example: Batch collection script

gather.mjs collects screen images by pattern — bypasses MCP and imports modules directly:

# Collect trending dashboard screens
PATTERN=Dashboard node gather.mjs

# Collect most popular checkout screens with more scrolling
PATTERN=Checkout SORT=mostPopular MAX_SCROLLS=12 node gather.mjs

Images are saved to data/downloads/{pattern}/ at full 1920px PNG resolution.

Project structure

mobbin-agent/
├── src/
│   ├── index.ts          # MCP server entry point (stdio transport)
│   ├── browser.ts        # Playwright browser lifecycle and interactions
│   ├── mobbin.ts          # Mobbin domain logic (login, extract, classify)
│   └── tools.ts           # MCP tool definitions and handlers
├── docs/                  # Full documentation
│   ├── INDEX.md           # Tool reference (all 10 tools)
│   ├── OPERATIONAL-GUIDE.md  # Workflows, rules, recipes
│   ├── connection.md      # MCP setup, session, direct usage
│   ├── tools/             # Detailed tool docs (5 files)
│   ├── reference/         # URL patterns, page types
│   └── troubleshooting/   # Known issues and solutions
├── gather.mjs             # Batch collection example script
├── data/
│   ├── session/           # Saved browser session (gitignored)
│   └── downloads/         # Downloaded images (gitignored)
├── MOBBIN-INSTRUCTIONS.md # Mandatory reading for AI agents
├── package.json
└── tsconfig.json

Documentation

Document	Purpose
MOBBIN-INSTRUCTIONS.md	Entry point — key rules for AI agents
Tool Reference	All 10 tools with links to detailed docs
Operational Guide	Rules, collection workflows, script templates, timeouts
Connection Guide	MCP config, browser lifecycle, session persistence, direct script usage
URL Patterns	Search templates, filter catalogs, CDN URLs
Page Types	Page classification reference
Troubleshooting	Known issues and solutions

Tech stack

Component	Technology
MCP server	@modelcontextprotocol/sdk 1.12
Browser automation	playwright 1.52 (Chromium)
Language	TypeScript 5.8 (ESM, strict)
Transport	stdio (JSON-RPC 2.0)
Session storage	Playwright storageState (JSON cookies)

License

MIT