mobbin-mcp

An MCP server that lets Claude, Cursor, Codex and other agents search Mobbin for UI references. Results come back as short text lists, not a wall of screenshots, and the agent loads images only for the screens it picks.

What you get

The tools form a path the agent walks, and each step returns the ids the next step needs:

1. Find apps by description ("AI app builder") or category, on iOS, Android or web.

2. Open an app to see its full catalogue of flows, ranked against a query. This step costs no AI credits.

3. Open a flow to see its ordered steps: each screen, its tags, and where the user tapped.

4. Get images only for the screens the agent chose.

It can also search screens and flows across apps, using Mobbin's AI search or its free plain ranking. Results are spread across apps, so less-mainstream apps aren't buried. There are also tools for Mobbin's website library (sites and page sections) and for looking up Mobbin's exact tag names.

Related MCP server: Mobbin Agent

Quick start

You need Node.js 22.13 or newer and a Mobbin account.

npx -y github:Bewinxed/mobbin-mcp

The server starts on http://127.0.0.1:8790 and prints the MCP URL. It needs no configuration. On first run it creates a data folder and an encryption key (see Configuration). Leave it running, then add http://127.0.0.1:8790/mcp to your agent.

Claude Code

claude mcp add --transport http mobbin http://127.0.0.1:8790/mcp

Then run /mcp in Claude Code, pick mobbin, and sign in in the browser window it opens. You can also sign in from the shell with claude mcp login mobbin.

Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "mobbin": { "url": "http://127.0.0.1:8790/mcp" }
  }
}

Cursor shows a sign-in prompt for the server in its MCP settings.

VS Code (GitHub Copilot)

Run MCP: Add Server from the Command Palette, choose HTTP, and enter http://127.0.0.1:8790/mcp. To edit the config by hand, run MCP: Open User Configuration, or create .vscode/mcp.json in a workspace:

{
  "servers": {
    "mobbin": { "type": "http", "url": "http://127.0.0.1:8790/mcp" }
  }
}

The root key in VS Code's own files is servers, not mcpServers. VS Code opens the browser for sign-in the first time it connects.

Windsurf

Open the raw mcp_config.json from Cascade's MCP menu (Open MCP config file) and add:

{
  "mcpServers": {
    "mobbin": { "serverUrl": "http://127.0.0.1:8790/mcp" }
  }
}

Then press refresh in the MCP panel and sign in when prompted.

Codex CLI

codex mcp add mobbin --url http://127.0.0.1:8790/mcp
codex mcp login mobbin

Other clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth can connect: give it the URL http://127.0.0.1:8790/mcp and no headers. The server supports Client ID Metadata Documents, Dynamic Client Registration, and loopback redirects on any port.

Claude Desktop and claude.ai

Custom connectors in Claude Desktop, claude.ai and the Claude mobile apps connect from Anthropic's cloud, not from your computer. They can't reach 127.0.0.1. To use them, host the server at a public https URL (see Hosting), then go to Settings → Connectors → Add custom connector with https://<your-host>/mcp. Leave the OAuth client ID and secret empty.

Signing in

When your agent connects for the first time, it opens a browser page served by your own mobbin-mcp:

1. Enter the email of your Mobbin account.

2. Mobbin emails you a 6-digit code. Enter it. If your account has a password, the page asks for that instead.

3. A consent screen shows which app is asking and where its access goes. Approve it.

The page signs in the same way mobbin.com/login does. Accounts that use company SSO can't sign in this way, and the page tells you so. Several people can share one server, and each signs in with their own Mobbin account.

Your agent stays signed in. When Mobbin ends the session, the agent is asked to sign in again.

Tools

AI search (mode: "ai", the default for a free-text query in the cross-app searches) runs Mobbin's AI search. One batch costs about $0.016 of your Mobbin AI credits and takes about 10 seconds. Later pages of the same query come from a cache when they can. mode: "fast" and tag filters are free and instant, but less precise.

Cross-app searches put apps outside Mobbin's most popular ones first (prefer: "distinctive", the default) and show at most a couple of results per app on each page. Use prefer: "popular" to keep Mobbin's own order, and exclude_apps to skip apps.

Hosting

The server only needs hosting if you want to use it from claude.ai or Claude Desktop, or share it with a team.

• Run it behind a reverse proxy that terminates HTTPS and passes every path through, including /.well-known/*.

• Set PUBLIC_URL to the public origin, for example https://mobbin.example.com. The MCP URL is then https://mobbin.example.com/mcp.

• Keep HOST=127.0.0.1 (the default) when the proxy runs on the same machine. Otherwise set HOST=0.0.0.0.

• Set TRUST_PROXY=1 (or the number of proxy hops) so the per-IP limits on sign-in emails see real client addresses.

• Persist DATA_DIR. It holds the database and, unless you set ENCRYPTION_KEY, the encryption key.

PUBLIC_URL=https://mobbin.example.com \
DATA_DIR=/var/lib/mobbin-mcp \
ENCRYPTION_KEY="<output of: openssl rand -base64 32, generated once and kept>" \
HOST=127.0.0.1 \
PORT=3000 \
TRUST_PROXY=1 \
npx -y github:Bewinxed/mobbin-mcp

To run from a clone instead: npm install (it builds automatically), then npm start.

Anyone who can reach the server can make it send Mobbin sign-in emails. So sends are limited to 3 per email address per 15 minutes and 10 per IP per hour, and each sign-in allows 5 wrong codes before it asks for a new one.

Configuration

Every setting is optional.

The default DATA_DIR is $XDG_DATA_HOME/mobbin-mcp when XDG_DATA_HOME is set. Otherwise it is:

• Linux: ~/.local/share/mobbin-mcp

• macOS: ~/Library/Application Support/mobbin-mcp

• Windows: %APPDATA%\mobbin-mcp

Privacy and security

• Where data lives. Everything is in DATA_DIR/mobbin-mcp.db (SQLite). The server contacts only Mobbin (mobbin.com and its Supabase project). The one exception is that it fetches an MCP client's own metadata document when that client signs in with one.

• Your Mobbin session is stored under your Mobbin user id, encrypted with AES-256-GCM. The key is ENCRYPTION_KEY or DATA_DIR/encryption.key. Your password and sign-in codes go to Mobbin and are never saved to disk.

• Tokens the server gives your agent are random values. The database holds only their SHA-256 hashes. Access tokens last 1 hour and refresh tokens 30 days, rotating on every use. Each token is bound to one user, one client and this server.

• Sign-out. When Mobbin rejects your session, the server deletes it along with every token issued to you.

• Exposure. By default the server listens on 127.0.0.1 only. Expose it beyond your machine only over HTTPS, as described in Hosting.

How it works

One Node process serves everything on PUBLIC_URL:

Redirect URIs must be https, or http on localhost/127.0.0.1. Loopback redirects match on any port (RFC 8252 §7.3).

The sign-in pages call Mobbin's own login endpoints. Mobbin's server action ids change with each Mobbin deploy, so the server reads them from https://mobbin.com/login when it first needs them, and reads them again if Mobbin says an id no longer exists.

License

MIT. Mobbin is a trademark of its owner. This project uses the name only to say what it works with.