AppScreens MCP Guide

The AppScreens MCP server lets AI agents — Claude Code, Cursor, Codex, and any other MCP client — query the screenshot archive directly: search apps, read screenshots, and browse version history. This guide covers every tool, how to connect each client, example workflows, and troubleshooting. For a quick overview, see the MCP feature page.

What the MCP does

AppScreens is a curated archive of top app store screenshots, each classified by layout pattern and ASO marketing strategy, with historical versions preserved. The MCP server exposes that archive to AI agents as a small set of read-only tools over Streamable HTTP (POST only) at https://appscreens.store/api/mcp. Instead of scraping the App Store or guessing, your agent gets structured results and direct, fetchable screenshot URLs.

Access requires a Pro plan: you authenticate with a personal token generated in Settings → MCP server.

Tool reference

All five tools are read-only. A typical session starts with list_categories / list_tags to discover filter values, then search_apps to find apps, then get_app or get_app_history for screenshots.

`search_apps`

Purpose: Search and filter the archive; the entry point for most workflows.
Inputs: query (name), platform (ios/android), category, layout[] and strategy[] tag slugs, page, limit (max 20). Filters combine with AND; slugs within layout/strategy combine with OR.
Returns: Paginated app summaries — enough to pick an app, then call get_app for screenshots.

`get_app`

Purpose: Read one app's full detail and current screenshots.
Inputs: app — an id or slug returned by search_apps.
Returns: App metadata plus the current screenshot set and any video previews, each with an absolute, publicly fetchable image URL.

`list_tags`

Purpose: Discover the layout and ASO-strategy vocabulary used as filters.
Inputs: type (optional) — layout or aso_strategy to narrow the list.
Returns: Tag names and slugs you can pass to search_apps as layout[] or strategy[].

`list_categories`

Purpose: Discover valid category filter values.
Inputs: None.
Returns: Every app category present in the archive, usable as the search_apps category filter.

`get_app_history`

Purpose: Read historical snapshots for an app (Time Machine).
Inputs: app (id or slug), page, limit (max 10).
Returns: Past screenshot snapshots, newest first, each with absolute image URLs — for tracking how a listing changed.

Image URLs from get_app and get_app_history are absolute and publicly fetchable — agents can load the actual screenshots, not just metadata.

Connect your client

First, generate a personal token in Settings → MCP server (Pro required). Your token is shown once — copy it immediately. Then pick your client below and paste the snippet, replacing the placeholder with your token.

Run this command in your terminal:

claude mcp add appscreens --transport http https://appscreens.store/api/mcp --header "Authorization: Bearer <YOUR_TOKEN>"

Replace <YOUR_TOKEN> with your personal token. Generate one in Settings (Pro required).

Any client that supports Streamable HTTP works — the Other tab gives a generic configuration. The endpoint is POST-only and expects an Authorization: Bearer <token> header.

Example workflows

Competitive ASO research

Ask your agent: “Find iOS finance apps that use social proof in their screenshots, and summarize the common layout.” The agent calls list_tags to resolve the social proof strategy slug, search_apps with platform: ios, category: Finance, and the strategy filter, then get_app on the top results to inspect the actual screenshots.

Tracking a listing over time

Ask: “Show me how Duolingo’s screenshots changed over time.” The agent runs search_apps to find the app, then get_app_history to pull historical snapshots newest-first and describe what changed between versions.

Building your own screenshot set

Ask: “What layout do the top meditation apps lead with?” Use the findings to design your own listing, then jump to the screenshot generator to produce every Apple-required resolution.

Troubleshooting

401 Unauthorized — the token is missing, malformed, or has been revoked/rotated. Confirm the Authorization: Bearer <token> header is present and matches your current token. If in doubt, rotate in Settings and update your client.
403 Forbidden — your account is not on Pro. MCP access requires a Pro plan; see pricing.
App not found — the id or slug isn't valid. Use search_apps to get current ids and slugs rather than guessing.
Lost your token — tokens are shown once. Rotate in Settings to get a new one; the old token stops working immediately.

Frequently asked questions

Do I need a Pro plan to use the MCP?

Yes. The MCP server authenticates with a personal token generated in Settings, which requires AppScreens Pro. Browsing the website is free, but agent access over MCP is a Pro feature.

Is the MCP read-only?

Yes. All five tools are read-only — agents can search and read the archive but cannot change any data.

What transport does the server use?

The server speaks Streamable HTTP (POST only) at https://appscreens.store/api/mcp. Authentication is a Bearer token in the Authorization header.

Are screenshot URLs directly downloadable?

Yes. get_app and get_app_history return absolute, publicly fetchable image URLs, so agents can load or reference the actual screenshots.

How do I rotate or revoke my token?

In Settings under the MCP server section, use Rotate to replace the current token (the old one stops working immediately) or Revoke to disconnect all agents.

Back to the MCP overview