Mobbin Skills And MCP

A local-first Mobbin integration for Mobbin that gives agents a durable design-reference workflow:

• Search Mobbin's reverse-engineered internal API for apps, screens, flows, site sections, filters, collections, and screenshots.
• Capture Mobbin flows, screens, and site sections directly into a project-aware local reference store.
• Reuse saved references through skills, MCP tools, prompts, contact sheets, visual similarity, PR reference packs, and memory exports.

Mobbin has no public API. This server was built by reverse-engineering their internal endpoints.

Quick Start

npm install -g @aos-engineer/mobbin-mcp
mobbin-mcp auth
mobbin-mcp skills install
mobbin-mcp skills status

For most agent workflows, the skills install is the recommended path. Native MCP setup is still available when a client needs MCP tools, resources, prompts, or inline image content.

Capture A Mobbin Flow In One Step

mobbin-mcp skill capture-flow '{"platform":"web","flow_actions":["Checkout"],"app_name":"Example","feature_area":"checkout","tags":["checkout"],"compute_visual_hashes":true}'

The generated artifact stores ordered steps, screen URLs, hotspot metadata, patterns, elements, source URLs, optional perceptual hashes, and project context. Use capture-screen for a single app screen and capture-site-sections for Mobbin's web-site section references.

Skills Mode

This repo now also ships focused agent skills so agents can use Mobbin workflows without loading the full MCP surface into context.

Source skills live in source/skills/:

• mobbin-search
• mobbin-capture
• mobbin-prompts
• mobbin-visuals

Build skill artifacts with:

npm run build

The generated skill bundles are copied to dist/skills/ plus provider folders for Codex, Claude Code, Gemini, OpenCode, Pi, Cursor, Rovo Dev, Qoder, Trae, Roo Code, GitHub Copilot, and related agents.

After installing the package globally, link the skills into all supported global CLI/IDE skill folders:

npm install -g @aos-engineer/mobbin-mcp
mobbin-mcp skills install

For most users this replaces MCP setup. The skills do not connect to the MCP server; they call the same package through mobbin-mcp skill ..., which reuses the same Mobbin auth, API client, local artifact store, prompt builders, and visual utilities behind the MCP tools. If you already added the Mobbin MCP server to Claude Code, Codex, or another CLI, you can remove that MCP entry after confirming the four Mobbin skills appear in the tool's skills list.

See docs/SKILLS.md for provider targets and release details.

The skill release covers the MCP tools, resources, and prompts through four focused skills. The full mapping is documented in docs/SKILLS.md.

What It Does Now

• search Mobbin apps, screens, flows, collections, and filters
• fetch full screenshots and optional dominant colors
• auto-detect the active repository from git, env vars, or cwd
• capture flows, screens, site sections, design references, implementation notes, decisions, and flow steps into a local project store
• preserve ordered flow steps, screen URLs, hotspot metadata, patterns, elements, source links, and optional visual hashes automatically
• search, update, delete, catalog, import, and export captured artifacts
• generate visual contact sheets from saved screens and flows
• compute perceptual hashes and find visually similar captured artifacts
• generate PR-ready reference markdown and diff-ready feature review reports
• seed the local store from Mobbin collection metadata
• optionally sync the local project store with a filesystem-backed shared store
• generate prompt-ready implementation, analysis, onboarding, and agent-specific context packs
• support Claude Code, Codex, Pi-style conversational agents, and Mem Palace export workflows through skills or MCP

What Changed From The Original Fork

The original upstream project was mainly a Mobbin browser for Claude.

This repo now adds:

• project-aware local artifact storage
• capture CRUD and cataloging
• MCP resources and reusable prompts
• multi-agent context generation
• export/import workflows for reuse across sessions and systems
• diagnostics and tests

Changed assumptions:

• no longer Claude-only
• no longer search-only
• no longer limited to transient one-off inspiration lookup

Removed limitations from the old shape:

• no requirement to manually scope references per project
• no dependence on ad hoc prompt writing every time you want to reuse a flow
• no lack of MCP resources/prompts for downstream agents

Tools

Search Mobbin

| Tool | Description | | --- | --- | | mobbin_search_apps | Search and browse apps by category and platform | | mobbin_search_sites | Search Mobbin's separate sites collection by name, tagline, or keyword | | mobbin_get_site_sections | Fetch copyable site sections with image URLs, source URLs, patterns, crop bounds, and video segment metadata | | mobbin_search_screens | Search iOS, Android, and Web app screens by UI patterns, elements, or text content | | mobbin_search_flows | Search user flows by action type | | mobbin_quick_search | Fast autocomplete search for apps or sites by name | | mobbin_popular_apps | Get popular apps grouped by category | | mobbin_list_collections | List your saved collections | | mobbin_get_screen_detail | Fetch a full screenshot image for a specific screen, with optional dominant color extraction | | mobbin_get_filters | Get all available filter values |

Capture And Reference Workflows

| Tool | Description | | --- | --- | | mobbin_doctor | Inspect auth, project detection, artifact storage, and runtime health | | mobbin_get_project_context | Auto-detect the current repository / working directory and show capture state | | mobbin_capture_artifact | Save screens, flows, notes, decisions, and implementation references into a local project index | | mobbin_capture_flow_from_search | Search Mobbin flows and save the selected iOS, Android, or Web flow with ordered steps, hotspots, metadata, and optional visual hashes | | mobbin_capture_screen_from_search | Search Mobbin screens and save the selected screen with patterns, elements, source URLs, and optional visual hash | | mobbin_capture_site_sections | Fetch Mobbin site sections and save selected ordered Web sections with image URLs, page URLs, pattern metadata, and optional visual hashes | | mobbin_get_captured_artifact | Fetch a single captured artifact by ID | | mobbin_update_captured_artifact | Update metadata, notes, steps, and decisions on an existing artifact | | mobbin_delete_captured_artifact | Remove an artifact from the local project index | | mobbin_search_captured_artifacts | Search previously captured artifacts by keyword, tag, type, app, or feature area | | mobbin_get_capture_catalog | Return facet counts for types, tags, apps, patterns, and feature areas | | mobbin_export_captured_artifacts | Export artifacts as JSON, Markdown, prompt packs, or Mem Palace JSONL | | mobbin_import_captured_artifacts | Import artifacts from a previous export | | mobbin_generate_feature_prompt | Generate implementation, analysis, or onboarding prompts from captured artifacts | | mobbin_generate_agent_context | Generate agent-specific context for Claude Code, Codex, Pi, or Mem Palace | | mobbin_generate_flow_contact_sheet | Generate a stitched PNG contact sheet from saved artifacts | | mobbin_find_similar_artifacts | Find visually similar artifacts using perceptual hashes | | mobbin_generate_pr_reference | Generate PR-ready markdown from selected references | | mobbin_sync_collections_to_artifacts | Seed the local store from Mobbin collection metadata | | mobbin_generate_feature_review | Generate a diff-ready intended-vs-actual feature review | | mobbin_sync_shared_store | Push, pull, or merge the local project store with a shared filesystem store |

Resources

| Resource | Description | | --- | --- | | mobbin://project/context | Current repo-aware project context detected from git or cwd | | mobbin://project/captures | Current project's captured artifact index as JSON | | mobbin://project/catalog | Current project's artifact catalog and facet counts |

Prompts

| Prompt | Description | | --- | --- | | mobbin_feature_implementation_prompt | Build a reusable implementation prompt from captured artifacts | | mobbin_feature_analysis_prompt | Build a feature-analysis prompt from captured artifacts | | mobbin_onboarding_brief_prompt | Build an onboarding brief from captured artifacts |

Setup

Prerequisites

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

Installation

Published package:

@aos-engineer/mobbin-mcp

Recommended skills-first install path:

npm install -g @aos-engineer/mobbin-mcp
mobbin-mcp auth
mobbin-mcp skills install

Contributor and fallback paths:

Option A: Run From GitHub

npx -y github:aos-engineer/mobbin-mcp auth

Option B: Run From A Local Checkout

git clone https://github.com/aos-engineer/mobbin-mcp.git
cd mobbin-mcp
npm install
npm run build
node dist/index.js

1. Authenticate

Option A: global install (recommended for Claude Code)

mobbin-mcp auth

Option B: npm package path

npx -y @aos-engineer/mobbin-mcp auth

Option C: GitHub fallback

npx -y github:aos-engineer/mobbin-mcp auth

Option D: local checkout

node dist/index.js auth

This is a one-time setup per machine. The session is stored globally and reused automatically across projects.

The CLI expects the two Supabase auth cookie chunks combined into one line:

1. Open mobbin.com and log in
2. Open the browser console (Cmd+Option+J)
3. Run:

copy(
  document.cookie
    .split("; ")
    .filter((c) => c.startsWith("sb-ujasntkfphywizsdaapi-auth-token.0=") || c.startsWith("sb-ujasntkfphywizsdaapi-auth-token.1="))
    .join("; ")
)

4. Paste that value into the CLI prompt

Your session is saved to ~/.mobbin-mcp/auth.json (or XDG_CONFIG_HOME/mobbin-mcp/auth.json) and automatically refreshed.

What gets copied? This copies only the two Supabase auth cookie chunks needed for Mobbin authentication. These are sensitive session credentials. They are stored locally on your machine at ~/.mobbin-mcp/auth.json and are never sent anywhere except to Mobbin's API.

Option B: Environment variable (manual)

1. Open mobbin.com in Chrome and log in
2. Open DevTools (Cmd+Option+I) → Application tab → Cookies → https://mobbin.com
3. Copy the full values of sb-ujasntkfphywizsdaapi-auth-token.0 and sb-ujasntkfphywizsdaapi-auth-token.1
4. Combine them into a single string:

sb-ujasntkfphywizsdaapi-auth-token.0=<value0>; sb-ujasntkfphywizsdaapi-auth-token.1=<value1>

5. Set MOBBIN_AUTH_COOKIE to that value (see step 2 below)

Environment variables

| Variable | Purpose | | --- | --- | | MOBBIN_AUTH_COOKIE | Manual auth input: combined sb-...auth-token.0/.1 cookie pair | | MOBBIN_DATA_DIR | Override the default data directory | | MOBBIN_AUTH_FILE | Override the auth session file path | | MOBBIN_PROJECT_ROOT | Explicit project root for capture storage | | PROJECT_ROOT | Alternative explicit project root | | MOBBIN_BASE_URL | Override the Mobbin site base URL | | MOBBIN_SUPABASE_URL | Override the Mobbin Supabase project URL | | MOBBIN_SUPABASE_PUBLISHABLE_KEY | Override the Mobbin Supabase publishable key | | MOBBIN_SUPABASE_COOKIE_PREFIX | Override the Supabase auth cookie prefix |

2. Install Skills Into Your CLI Or IDE

Skills are the recommended setup for Claude Code, Codex, Gemini, OpenCode, Pi, Cursor, Rovo Dev, Qoder, Trae, Roo Code, GitHub Copilot, and related agents.

mobbin-mcp skills install
mobbin-mcp skills status

Upgrade later with:

npm install -g @aos-engineer/mobbin-mcp@latest
mobbin-mcp skills install --force

This creates global symlinks to the package's built skills. Restart any running CLI or IDE after installation so it can discover them.

You do not need to add the Mobbin MCP server when the skills are installed. Keep MCP only if you specifically want native MCP tools/resources/prompts or MCP inline image responses.

Optional: Add MCP To Claude Code

Recommended global install path:

claude mcp add mobbin -- mobbin-mcp

npm fallback:

claude mcp add mobbin -- npx -y @aos-engineer/mobbin-mcp

GitHub fallback:

claude mcp add mobbin -- npx -y github:aos-engineer/mobbin-mcp

If you used the CLI auth command (Option A), no additional config is needed — the server reads from ~/.mobbin-mcp/auth.json automatically.

If using the environment variable (Option B), pass it when adding:

Recommended global install path:

claude mcp add mobbin -e MOBBIN_AUTH_COOKIE="sb-ujasntkfphywizsdaapi-auth-token.0=...; sb-ujasntkfphywizsdaapi-auth-token.1=..." -- mobbin-mcp

npm fallback:

claude mcp add mobbin -e MOBBIN_AUTH_COOKIE="sb-ujasntkfphywizsdaapi-auth-token.0=...; sb-ujasntkfphywizsdaapi-auth-token.1=..." -- npx -y @aos-engineer/mobbin-mcp

GitHub fallback:

claude mcp add mobbin -e MOBBIN_AUTH_COOKIE="sb-ujasntkfphywizsdaapi-auth-token.0=...; sb-ujasntkfphywizsdaapi-auth-token.1=..." -- npx -y github:aos-engineer/mobbin-mcp

Optional: Add MCP To Codex

If your Codex runtime is configured to use stdio MCP servers, prefer the installed binary:

{
  "mcpServers": {
    "mobbin": {
      "command": "mobbin-mcp"
    }
  }
}

Package fallback:

{
  "mcpServers": {
    "mobbin": {
      "command": "npx",
      "args": ["-y", "@aos-engineer/mobbin-mcp"]
    }
  }
}

For a local checkout, use:

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

Optional: Claude Desktop MCP

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mobbin": {
      "command": "npx",
      "args": ["-y", "@aos-engineer/mobbin-mcp"]
    }
  }
}

Optional: Local MCP Alternative

If you prefer a pinned local checkout instead of npx, build once locally and point your MCP client directly at the compiled server:

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

Example prompts

• "I'm designing a checkout flow for a food delivery app — show me how top apps like DoorDash and Uber Eats handle it"
• "Pull up the Duolingo onboarding flow and walk me through each screen's design decisions"
• "Find login screens that use bottom sheets and extract the color palette — I need inspiration for our auth redesign"
• "Compare how fintech apps handle settings screens — show me examples from Robinhood, Cash App, and Venmo"
• "Search for screens with card-based layouts in travel apps, then show me the best one in detail"
• "What UI patterns are trending right now on iOS? Show me the top screens"
• "Save this onboarding flow as a captured artifact for our auth redesign and tag it signup, ios, and trust-building"
• "Find the first Web checkout flow for a marketplace app and capture it with visual hashes for our cart redesign"
• "Capture the pricing and hero sections from this Mobbin site reference as a Web design artifact"
• "Generate a Codex-ready implementation prompt for the checkout feature using our saved checkout references"
• "Export our saved growth-onboarding captures as Mem Palace JSONL"
• "Give me an onboarding brief for the billing area using everything tagged billing"
• "Generate a contact sheet for our saved onboarding references"
• "Find visually similar artifacts to this saved checkout screen"
• "Generate PR reference markdown for the billing redesign work"
• "Sync my Mobbin collections into this project's local artifact store"
• "Compare intended onboarding references against the actual shipped onboarding artifacts"

How it works

Mobbin is a Next.js app backed by Supabase. The skills and MCP server call Mobbin's internal API routes (/api/content/search-apps, /api/content/search-screens, etc.) using your session cookie for authentication. Tokens are automatically refreshed via Supabase's /auth/v1/token endpoint before they expire, and persisted back to ~/.mobbin-mcp/auth.json when using the CLI auth method.

Screen images are served through Mobbin's Bytescale CDN. The MCP mobbin_get_screen_detail tool can return the fetched screenshot as an inline image content block. The skills path uses mobbin-search / screen-detail, which prints metadata and optional dominant colors in CLI output.

Captured artifacts are stored locally in a project-aware index under ~/.mobbin-mcp/projects/<project-id>/artifacts.json. The CLI auto-detects the active repository from git when possible, then falls back to the current working directory. This makes saved Mobbin references portable across skills and MCP clients while still being scoped to the project you are working on.

Repeated Mobbin reads are cached in-process for short periods to reduce redundant API traffic for common searches, autocomplete, filters, collections, and popular app lookups.

Artifacts can include:

• feature area, journey, session name, and participants
• implementation hints and decision logs
• ordered steps with patterns, elements, and hotspot geometry
• references to URLs or other saved artifacts
• collection links and preview-screen derived references
• cached visual hashes for similarity search

Recommended Workflow

1. Search Mobbin for relevant apps, screens, and flows.
2. Inspect screenshots with mobbin_get_screen_detail.
3. Save durable references with mobbin_capture_flow_from_search, mobbin_capture_screen_from_search, mobbin_capture_site_sections, or the lower-level mobbin_capture_artifact.
4. Tag and organize them with feature area, journey, and decision notes.
5. Review the saved corpus with mobbin_search_captured_artifacts and mobbin_get_capture_catalog.
6. Generate contact sheets, PR reference packs, or feature review reports as needed.
7. Generate implementation, analysis, onboarding, or agent-specific context from the saved artifacts.
8. Optionally sync the project store with a shared filesystem-backed store for team reuse.

Storage Layout

~/.mobbin-mcp/
  auth.json
  projects/
    <project-id>/
      artifacts.json

The server is local-first. It does not require a shared backend to be useful, but captured artifacts can be exported and re-imported across machines, repos, or agents.

Development

npm install
npm run build
npm run lint
npm test

Additional docs:

• Architecture
• Portability
• Skills
• Workflows
• Release
• Implementation Ideas

Project structure

src/
  index.ts              # MCP server entry point, CLI routing, and tool registration
  constants.ts          # API URLs, keys, and config
  types.ts              # TypeScript interfaces for Mobbin models and captured artifacts
  cli/
    auth.ts             # Interactive CLI authentication flow
  services/
    auth.ts             # Token parsing, expiry checks, and auto-refresh
    api-client.ts       # HTTP client for all Mobbin API endpoints with caching/timeouts
  utils/
    auth-store.ts       # Persistent session storage (~/.mobbin-mcp/auth.json)
    artifact-store.ts   # Project-aware capture store, search, import/export, and prompt generation
    capture-workflows.ts # Direct flow/screen/site-section capture orchestration
    formatting.ts       # Markdown formatters for tool responses
    project-context.ts  # Git / cwd auto-discovery for repository-aware capture
docs/
  ARCHITECTURE.md       # Current architecture and MCP surface
  PORTABILITY.md        # Agent portability strategy
  SKILLS.md             # Skills install, upgrade, and MCP coverage
  WORKFLOWS.md          # Recommended usage patterns
  RELEASE.md            # Release checklist and npm publish process
  IMPLEMENTATION_IDEAS.md # Next expansion ideas
test/
  *.test.js             # Node test coverage for capture store and project detection

Roadmap

Priority next features:

1. Item-level collection sync once additional Mobbin collection-content endpoints are discovered.
2. Embedding-backed or hybrid visual/text similarity ranking beyond perceptual hashes.
3. Automatic screenshot capture of shipped application flows for direct intended-vs-actual comparison.
4. Shared HTTP-backed team storage instead of filesystem-only shared sync.
5. Design-system extraction from saved references into reusable implementation assets.

License

MIT