---
title: "search_app_listing"
description: "Find the user’s app on the App Store so a saved project carries its real identity."
canonical: "https://shotops.dev/docs/mcp/reference/search_app_listing"
last_updated: "2026-09-22"
shotops_mcp_version: "0.9.8"
result_contract_version: "2.0.0"
---
# search_app_listing

Find the user’s app on the App Store so a saved project carries its real identity.

## What it does

- Read-only
- Idempotent
- Open world
- Account required

Stop typing what Apple already published. Search by app or developer name and each result comes back with the app’s exact name, its seller, its icon, its bundle ID and its numeric app ID, plus the App Store Connect languages and the iPhone devices ShotOps would apply if you linked it. Hand the chosen result’s app ID to save_project as `appListing` and the project it creates is the real app rather than a guess. Read-only: it renders nothing, writes nothing and changes no project.

You can ask: “Find the Tidebook app so the project carries its real name and languages.”

Open-world because the answer comes from Apple, not from ShotOps: the same term can return something different tomorrow, so the result is not a thing to cache.

Finding a public listing proves nothing about who owns the app. The bundle ID on the project stays freely editable, and a store release verifies ownership separately.

## Input

- `term`stringrequiredat least 1 characterat most 200 characters What to search the App Store for — the app name as the user said it ("Duolingo"), or the developer's name. Each result carries the app ID to pass as save_project's `appListing`.
- `country`stringoptionalpattern ^[A-Za-z]{2}$ The two-letter App Store storefront to search, e.g. "dk". Defaults to "us". An app released in one country only is invisible to a search of any other, so pass the user's own storefront when they say the app is not showing up.

## Result

- `ok`booleanoptional
- `results`arrayoptional each item object - `appId`stringrequired Apple’s numeric app ID, as a string. Pass it as save_project’s `appListing`. - `bundleId`stringrequired - `name`stringrequired - `seller`stringrequired - `storeUrl`stringoptional The listing’s own App Store page. Carries the storefront, so it is the reference to reuse for a non-US app. - `iconUrl`stringoptional The app icon on Apple’s CDN. Shown as project chrome; never downloaded and never rendered into a strip. - `locales`arrayrequired The App Store Connect locales this listing’s languages map to, in catalog order. each item string - `baseLocale`stringrequired The caption base the other locales inherit from. Derived — Apple never says which language is primary. - `outputs`arrayrequired The ShotOps output devices this listing fills. iPhone only, and EMPTY for an iPad-only app. each item string - `supportsIpad`booleanrequired The listing supports iPad. Recorded, and applied to no output until iPad panels ship. - `storefront`stringrequired The two-letter storefront this was read from. It decides `baseLocale`. - `droppedLanguageCodes`arrayoptional Apple language codes this build maps no App Store Connect locale for. Omitted when nothing was dropped. each item string
- `message`stringoptional

## Example

That request maps to this call:

```
{
  "name": "search_app_listing",
  "arguments": {
    "term": "Tidebook tide forecast"
  }
}
```

Up to ten matching apps. Each carries `appId`, `bundleId`, `name`, `seller`, `iconUrl`, `storeUrl`, and the `locales`, `baseLocale` and `outputs` linking it would apply. Let the user pick — the icon and the seller are what prove which app is theirs.

## Access and cost

- Needs an account, on both doors. An unsigned local server has no way to reach the App Store and says so.
- Free and unmetered. Searching spends no cloud credits.
- Apple’s public listing data only — the same page anyone can open. No Apple or App Store Connect credential is involved.

## When it refuses

- **The user’s app does not come back.**
  An app released in one country is invisible to a search of any other. Pass `country` with their two-letter storefront, or ask them for the App Store link and hand that straight to save_project’s `appListing`.

- **Several results look alike.**
  Do not guess. Show the names, sellers and icons and let the user say which one is theirs — linking the wrong app puts the wrong bundle ID and the wrong language list on the project.

- **The reply says the App Store is rate-limiting or unreachable.**
  Apple throttles lookups per server. Wait a moment and try again; nothing was saved or changed, and the user can still name the project themselves.

## Where this fits

- [Linking a project to its App Store listing](https://shotops.dev/docs/mcp/workflows/saved-project)

## What the agent is told

The title and description the server publishes on `tools/list` — this is the copy a model chooses between, reproduced verbatim.

Find an app on the App Store

Find the user’s app on the App Store so the project you save carries its real identity instead of a name you typed: search by app or developer name and every result comes back with the app’s exact name, its seller, its icon, its bundle ID and its numeric app ID, plus the App Store Connect languages and the iPhone device set ShotOps would apply. Let the USER confirm which one is theirs — the icon and the seller name are what prove it — then pass that result’s `appId` (or `storeUrl`) as `appListing` on save_project. Pass `country` to search another storefront; an app released in one country is invisible to a search of any other. Free and unmetered: it renders nothing, saves nothing and changes no project. Finding a public listing proves nothing about who owns the app, and no Apple or store credential is involved. Needs an account.