Mobbin MCP: Real Design Examples for AI Agents

Mobbin MCP is Mobbin’s official remote MCP server at https://api.mobbin.com/mcp. It lets a coding agent search Mobbin’s library of screenshots from shipped iOS and web products through three tools: search_screens, search_flows and search_sections. Access uses OAuth and requires a paid Mobbin plan (Pro, Team or Enterprise).

Ask an agent to build a paywall and you get the screen every developer gets: a centred card, three feature bullets, and a gradient button. It is the statistical average of every paywall in the training data. The product teams whose paywalls you admire made specific decisions about plan toggles, trial timelines and close buttons, and your agent cannot see any of them.

This page is for developers building UI with an agent and for tech leads who want design decisions in agent-built screens to be traceable to evidence rather than taste. It covers the official Mobbin server in depth, then the alternatives that solve the same problem.

What you get from Mobbin MCP on this page

Setup for the official Mobbin MCP server in Claude Code, Codex and Cursor, with the OAuth step for each.
The three tools, their parameters, and the query patterns that return useful results.
Five copy-paste prompts: research before building, flow research, competitor audits, landing-page sections and reference-to-component.
A verification loop that checks the built screen against the references without reading every line of UI code.
A map of the alternatives: Refero MCP, community servers, and screenshotting live products with a browser MCP server.

What does Mobbin MCP give an agent?

Mobbin is a curated library of screenshots from real apps, tagged by pattern, flow and app. The MCP server exposes that library to agents over the Model Context Protocol. The archived community server’s README described the library as “600k+ screens from 1,100+ apps” (pdcolandrea/mobbin-mcp, archived 2026-05-15; secondary, because Mobbin’s own MCP page could not be read from our environment on 2026-09-26). The server is listed in the Official MCP Registry (API entry) as com.mobbin/mobbin (version 1.0.1, active, published 2026-06-03), and Mobbin publishes no install count for it as of 2026-09-26.


Endpoint	`https://api.mobbin.com/mcp` (remote, Streamable HTTP)
Authentication	OAuth. A browser window opens on first connect; there is no API key to manage
Plan requirement	Pro, Team or Enterprise. A free account cannot use the tools
Rate limit	`mobbin-mcp-cli` 0.2.0 retries HTTP 429 responses using `Retry-After` with backoff, so expect rate limiting under parallel searches
Platforms in the tools	`ios` and `web` only
Writes	None. All three tools are read-only searches

Because the server is remote, nothing runs on your machine. The trade-off is that access follows your Mobbin subscription, not your repository.

How do you connect Mobbin MCP to Claude Code, Codex and Cursor?

The endpoint and the OAuth step are the same everywhere; only the command differs.

Checked against Claude Code 2.1.283 (claude mcp --help):

claude mcp add --scope user --transport http mobbin https://api.mobbin.com/mcp
claude mcp login mobbin

--scope user makes the server available in every project, which suits a reference library better than per-repository config. To share it with the team instead, use --scope project, which writes this entry to .mcp.json:

{
  "mcpServers": {
    "mobbin": {
      "type": "http",
      "url": "https://api.mobbin.com/mcp"
    }
  }
}

Each teammate still signs in with their own Mobbin account. Inside a session, /mcp also lists the server and offers Authenticate.

Checked against codex-cli 0.157.1 (codex mcp add --help, codex mcp login --help):

codex mcp add mobbin --url https://api.mobbin.com/mcp
codex mcp login mobbin

codex mcp add writes a global entry to ~/.codex/config.toml:

[mcp_servers.mobbin]
url = "https://api.mobbin.com/mcp"

codex mcp login runs the OAuth flow in your browser.

Put the remote-server entry in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). This is the entry from Mobbin’s official server README; it was not tested in Cursor itself:

{
  "mcpServers": {
    "mobbin": {
      "url": "https://api.mobbin.com/mcp"
    }
  }
}

Mobbin’s README says that on first use the client opens a browser window to sign in to Mobbin and authorize access through OAuth. Cursor’s MCP documentation lists OAuth support for remote servers (secondary: cursor.com could not be read from our environment on 2026-09-26).

To confirm the connection, paste a prompt that forces a tool call:

Call the Mobbin search_screens tool with the query "onboarding screen with progress indicator", platform ios, limit 3. List the app name and mobbin_url for each result. Do not answer from memory.

A working server returns real app names and mobbin_url links. Generic advice with no links means the tool was not called.

Which tools does Mobbin MCP expose?

The server is deliberately small: three searches and no write operations.

Tool	What it searches	Main parameters
`search_screens`	Individual UI screens	`query`, `platform` (required: `ios` or `web`), `limit` (1–30), `mode` (`deep` or `standard`), `exclude_screen_ids`
`search_flows`	Multi-step journeys such as onboarding or checkout	`query`, `platform` (required: `ios` or `web`), `limit` (1–10), `page`
`search_sections`	Website sections such as pricing, hero or footer	`query`, `limit` (1–30), `page`

All three accept image_format (webp or jpg) and task_intent. The parameter shapes above are cross-checked against the community mobbin-mcp-cli 0.2.0 client (npm, published 2026-09-19), which wraps the official server.

Details that matter in practice:

mode accepts deep or standard for screen searches (fast is deprecated, per mobbin-mcp-cli 0.2.0). Mobbin’s feature documentation could not be read from our environment on 2026-09-26, so this page does not describe how the two modes rank results. Try both on the same query and keep the one whose results you prefer.
search_sections has no platform parameter: sections are a web concept.
Paginated results carry page and has_next_page. For screens, pass the IDs you have already seen in exclude_screen_ids instead of paging.

What a Mobbin search result contains

Each result pairs an inline low-resolution preview image with structured metadata: the app, the platform, a high-resolution image_url and the canonical mobbin_url (per the mobbin-mcp-cli 0.2.0 README). The inline image is the point. The agent does not read a description of a paywall; it looks at the pixels and extracts the layout decisions itself. The mobbin_url lets the agent cite every screen it used, and lets you open the reference in Mobbin to see the surrounding flow.

How do you write Mobbin queries that return useful results?

Query quality decides whether you get references or noise:

Describe one screen or one journey per query. “Checkout with payment method selection” works. “Checkout and onboarding and settings” does not; search three times.
Name the visible elements and how they relate. “Login screen with biometric authentication”, “checkout page with promo code field and Apple Pay button”.
Put an app name in the query to focus on it. “Duolingo onboarding” is the fastest way to study one product’s approach.
Avoid negations and vague style words. “Without ads”, “modern” and “clean” do not help the ranking. Keep the platform out of the query text; that is what platform is for.

Workflow: research, build, then verify against the references

The loop that pays off is plan, build and verify, with the references as the acceptance evidence. It fits inside the four-artifact design-to-code pipeline as the research input to the visual direction.

Research before any code. The agent searches, studies the screenshots and writes the recurring decisions to a notes file with a mobbin_url per decision.

Before writing any code: search Mobbin screens for "paywall with annual and monthly plan toggle and free trial button", platform ios, mode deep, limit 6. Study the screenshots and write docs/design/paywall-notes.md with the recurring decisions: plan card layout, badge placement, trial timeline framing, close button, CTA copy. Give every decision the mobbin_url of at least two screens that show it. Then stop and wait for my review.

Review the notes, not the pixels. You approve or edit a one-page list of decisions, each backed by links. This is the human sign-off, and it takes minutes.

Build from the approved notes. Screenshots can now leave the context; the text notes are what the build needs.

Implement the paywall in src/components/Paywall.tsx following docs/design/paywall-notes.md exactly. Use our existing Button and Card components. When you finish, append a checklist to the notes file with one line per decision, marked done or deviated, and a reason for every deviation.

Verify the built screen against the notes. Use a browser MCP server or Playwright to render the component and check each decision, then keep the check as a test.

Start the dev server, open the paywall route with the Playwright MCP server, and take a screenshot at 390x844. For each decision in docs/design/paywall-notes.md, state pass or fail with the evidence you see in the screenshot. Then write a Playwright test that asserts the structural decisions (annual plan selected by default, trial timeline visible, a single primary CTA, close button reachable by keyboard) and run it.

What proves the result: the decisions file (every choice traceable to at least two shipped products), the pass/fail checklist, and a Playwright test that CI keeps. You review a one-page decision list and a test result instead of the component source. For the signed visual acceptance step, see visual acceptance before frontend implementation; for the browser side, see Playwright MCP vs Playwright CLI.

More Mobbin prompts: flows, competitors and landing pages

Research a flow’s step order

search_flows answers sequencing questions that single screens cannot: how many steps, in what order, and where signup or permission prompts sit.

Search Mobbin flows for "onboarding with personalization questions before account creation", platform ios, limit 3. For each flow, list the steps in order with the mobbin_url, and mark where signup happens. Then propose an onboarding order for our app that defers signup as late as these apps do, and flag any step our current onboarding in src/onboarding/ is missing.

Compare two competitors on the same screen

Because results carry the app name, the agent can compare how specific products solve the same problem.

Search Mobbin screens for "Airbnb search results with map" and then "Booking.com search results with map", platform web, limit 4 each. Compare them in a table: layout split, filter placement, card density, map interactions. Recommend which decisions our listings page should adopt, with the mobbin_url for each.

Build a landing page from sections

For marketing sites, section-level search beats screen-level search: you assemble a page from strong sections.

Search Mobbin sections for "pricing section with three-tier comparison table and highlighted recommended plan", limit 5. Describe the structure of the three strongest examples with their mobbin_url. Then rebuild src/components/PricingSection.astro with that structure, using our real plans and copy from src/lib/pricing.ts.

Pair Mobbin with a component registry

Mobbin answers what to build; a component registry such as the shadcn/ui MCP server answers what to build it with.

Search Mobbin screens for "web settings page with grouped sections and inline toggles", platform web, limit 4. Pick the clearest layout and explain why. Then use the shadcn MCP server to find matching components (Switch, Separator, Card) and implement the settings page with them, keeping the grouping and hierarchy of the reference.

How much context does Mobbin MCP use?

Every screen result carries an inline preview image into the agent’s context window. The previews are low-resolution, and the high-resolution image_url is only a link in the metadata, so it is not loaded into context unless the agent downloads it. Even so, images cost more than text, and a call’s cost grows with limit.

We have no measured figure for this page. On 2026-09-26 our environment could not reach api.mobbin.com and has no paid Mobbin account, so the /context before-and-after measurement in Claude Code 2.1.283 could not be run. Take it yourself before you set a team default:

Ask for three to eight screens in a coding session. That is enough to see a pattern.
Use exclude_screen_ids to get new screens instead of re-fetching ones you have seen.
Research early, then distil. Write the decisions to a text file and let the screenshots leave the context.
Measure it. In Claude Code, run /context once after connecting (the tool definitions) and again after one search_screens call with limit 3 (the per-call cost).

For the general techniques, see reducing MCP token cost.

Image URLs expire. The high-resolution image_url links stop working after 30 days (per the mobbin-mcp-cli README). Cite mobbin_url in notes and pull requests, never image_url.
There is no Android value. platform accepts ios and web only. An agent asked for Android patterns has no Android value to pass, so it may silently search iOS instead; check the platform in the tool call.
The unofficial mobbin-mcp is dead. The community server pdcolandrea/mobbin-mcp used browser session cookies and was archived on 2026-05-15; its README tells users to switch to the official server. Remove it if an old config still has it.
References, not templates. Mobbin screens are copyrighted UI from real products. Extract the pattern; do not tell an agent to clone a specific app’s screen pixel for pixel.

Which alternatives give agents design examples over MCP?

The options fall into three groups: curated libraries with official MCP servers, community servers that search public galleries, and screenshotting live products yourself.

Refero MCP

Refero is the other curated screenshot library with an official MCP server, at https://api.refero.design/mcp with OAuth sign-in. Its README describes “150,000+ real app screens, and 6,000+ user flows” and says live research requires a paid Refero plan. Refero also ships a plugin that wraps the server in a research-first workflow; as of 2026-09-26 the referodesign/refero_skill repository has 286 GitHub stars.

In a Claude Code session (commands from the Refero README):

/plugin marketplace add referodesign/refero_skill
/plugin install refero@refero

codex plugin marketplace add referodesign/refero_skill
codex plugin add refero@refero

The Refero README lists the Cursor plugin as pending marketplace approval. Until then, add https://api.refero.design/mcp as a remote server in .cursor/mcp.json, the same way as Mobbin above.

	Mobbin MCP	Refero MCP
Library focus	iOS and web screens, flows, website sections	App screens and user flows (150,000+ / 6,000+ per its README)
Search filters	Explicit `platform: ios` or `web`; separate section search	Not documented in the README
Endpoint	`https://api.mobbin.com/mcp`	`https://api.refero.design/mcp`
Auth and plan	OAuth; Pro, Team or Enterprise	OAuth; paid Refero plan
Packaged workflow	None from Mobbin; the community `mobbin-mcp-cli` ships a skill	Official plugin for Claude Code and Codex

The verifiable difference is in the tools: Mobbin lets the agent filter by platform: ios or web and search website sections on their own. If you need either, start with Mobbin. Otherwise run the same three queries through both and keep the one whose results your designers agree with.

Community servers that search public galleries

design-inspiration-mcp-server (MIT) does not access any library directly. It runs Google searches through the Serper API, scoped to Dribbble, Behance, Awwwards, Mobbin and Pinterest, and can extract design tokens (colours, typography, spacing) from live sites; token extraction also needs the dembrandt CLI installed globally (npm install -g dembrandt). You get breadth for the cost of a Serper key, but only what Google indexed, not semantic search over a curated taxonomy. It installs from a local build, not from npm.

Screenshot live products with a browser MCP server

The no-subscription option: point a browser automation MCP server at products you admire and let the agent take its own screenshots. It reaches what no library has, such as a competitor’s app behind a login or yesterday’s redesign. What you lose is curation: no taxonomy, no “twenty fintech paywalls” in one query, and agent time spent navigating. Use a library for pattern research and a browser for targeted reconnaissance.

Design MCP servers that answer a different question

Server	What it provides	The question it answers
Figma MCP	Your own design files: layers, tokens, variables	“What did our designer specify?”
shadcn/ui MCP	Component registry, docs, install commands	“What do I build it with?”
Mobbin or Refero	Screens from shipped products	“What does good look like elsewhere?”

A design-capable agent setup often combines all three layers.

When Mobbin MCP breaks

Tools connect but every call fails with an authorization error. Mobbin MCP requires a Pro, Team or Enterprise plan (mobbin-mcp-cli README), so an authorization error on every call usually means the signed-in account has no such plan. Upgrade, or sign in with the account that has the plan: remove the stored credentials (claude mcp logout mobbin in Claude Code; codex mcp logout mobbin in Codex) and log in again.

The OAuth window never completes. The sign-in redirects back to a local callback; one possible cause is a VPN or strict firewall blocking that redirect. Try disconnecting the VPN for the first sign-in, or use claude mcp login mobbin --no-browser or codex mcp login mobbin --no-browser, which print the authorization URL so you can finish the flow and paste the callback URL back. For other connection errors, see MCP connection issues.

HTTP 429 responses. The agent fanned out too many parallel searches. Wait for the Retry-After interval, then ask the agent to run the searches one at a time.

Results are irrelevant. Almost always a query problem: several intents in one query, negations, or style adjectives. Rewrite it as one concrete visual description, and for screens try the other mode value.

Links in the notes stop working a month later. Someone cited image_url. Replace it with the result’s mobbin_url, which is the canonical link.

The agent’s design looks nothing like the references. The screenshots left the context before the decisions were written down. Rerun step 1 of the workflow and make the build prompt reference the notes file, not “the screens you saw”.

Where to go next with design references for agents

Visual acceptance before frontend implementation Turn references into a signed visual acceptance file and check the built screen against it.

Figma and design system MCP Connect your own design files, the other half of a design-capable agent.

Best frontend skills Skills that shape design quality and review the result.

Playwright MCP vs Playwright CLI Verify the built screen in a real browser and keep the check in CI.