@asolens/mcp

@asolens/mcp

See how your app really performs in App Store search — and how much to trust every number you get.

ASOLens gives your AI assistant live App Store data. You ask a question in plain language; it goes and looks.

claude mcp add asolens -s user -- npx -y @asolens/mcp

Most of it needs no account and no API key — install it and start asking. Only two things need a credential you set yourself: reading your own listing, and search volume (paid, and us only).

The full guide — every setting, and worked examples from real runs — is at asolens.danielhan.dev/guide.

What you can do with it

• Find where you rank for any keyword, in any of 17 storefronts — and how many apps you were ranked against, which is what decides whether the rank means anything at all.
• Check what a keyword really means to searchers before you build a strategy on it. That is the example below, and it is the thing a rank alone cannot tell you.
• Audit your keyword field — which words are working, which are dead weight, and which could not be tested.
• Size up the competition — who owns your niche, where they are weak, and what their users complain about.
• Prove a change worked. Snapshot before, ship the metadata, diff after.

The thing a rank cannot tell you

Ask the App Store what people type after division:

division -> the division resurgence  ·  division math games  ·  the division 2
            division games  ·  division math  ·  division flash cards
            division 2 map  ·  division mobile  ·  division two
            lexus, a division of toyota motor sales, u.s.a.

Three unrelated audiences in one word: people hunting Ubisoft's shooter, people wanting maths practice, and someone looking for a car dealership. Ranking near the top for division tells you nothing about which of them you reached.

It is not a rare case:

• After addition, the top two suggestions are addition financial and addition financial credit union — a credit union.
• After table, people type open table, tablecheck, tabelog — restaurant booking — and tableau, the business-intelligence tool.

A maths app can rank beautifully for all three and get no users from any of them. ASOLens checks this for free, in every storefront, before you commit.

(Measured 2026-09-06 in the us storefront. Autocomplete drifts — run it yourself and see what you get.)

What makes it different

Every number tells you how much to trust it. Each value comes back labelled observed (with where it came from and when), modelled (with the model and the inputs it used), or unavailable (with the reason, and what would fix it). No score with hidden inputs, ever.

It refuses to guess. No download estimates, no revenue estimates. Nobody outside Apple knows those, and a number you cannot check is worse than no number — because you will act on it.

It tells you when its own answer is suspect. That is the unusual part:

• It tests its probe word against the real store before trusting it. A word your own app already dominates makes every keyword look perfect — one auto-picked word read a keyword field as 29 of 29 words working, which was pure brand recall. Words like that are detected and rejected now, and it says so.
• It separates real placements from arithmetic ones. Ranking in the top 10 of a search that returns 7 apps is not a result, and is counted separately.
• It flags a keyword it could not test, rather than scoring it anyway.

It runs locally and needs no account. Storage is a SQLite file in ~/.asolens/, and with no credentials set it reaches only Apple's public endpoints, carrying no key, no account and nothing that identifies you or your install. Two features reach past that, and each needs credentials you set yourself — see What leaves your machine.

It cannot change your listing. ASOLens only ever reads from Apple. There is no write path to your App Store record, for any tool.

Install

Requires Node.js >= 22.13.0, for the built-in node:sqlite module (check with node --version); the database needs no separate install.

Claude Code

claude mcp add asolens -s user -- npx -y @asolens/mcp

-s user makes it available in every project. Drop the flag for the current project only, or use -s project to commit the registration for your team. Check it with claude mcp list, then restart Claude Code.

Claude Desktop — add to your MCP config file:

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

Codex — add to config.toml (check your Codex version's docs — the MCP config key and format have changed across releases):

[mcp_servers.asolens]
command = "npx"
args = ["-y", "@asolens/mcp"]

The first run creates ~/.asolens/ (config file + SQLite database) and prints a ready line on stderr once connected. To remove it again: claude mcp remove asolens -s user.

A first session

If you have just installed it and want the shortest useful path:

• "Find my app on the App Store." — resolves the id everything else uses.
• "What ranks for <your main keyword> in <your biggest market>?" — the ground truth you are about to reason from.
• "Suggest autocomplete keywords for <that keyword>." — free, and the fastest way to find out whether searchers mean what you assume. This is the step that catches a division before you build a strategy on it.
• "Audit my keyword field in <that market>." — needs App Store Connect credentials; without them, steps 1-3 still work.

Nothing here can change your App Store listing. ASOLens only ever reads from Apple — the App Store Connect client issues no write of any kind, not for any tool. It writes plenty locally: almost every tool caches what it fetched into the SQLite file under ~/.asolens/, which is what makes a second call cheap and a snapshot_diff possible. One write leaves your machine, and not to Apple: a DataForSEO lookup POSTs an app id to create a billable task -- carrying the keyword text too, when you are pricing keywords by name.

More questions to ask, most with a worked example: Recipes.

Tools

Fifteen tools. Eleven need nothing at all — no account, no key, no signup.

Tool	What it does	Needs
find_app	Finds an app by id, App Store URL or name.	—
app_snapshot	One app's current listing, plus that developer's other apps in the storefront.	—
search_ranks	The ranked apps for one keyword in one country, as App Store search lists them today.	—
keyword_ranks	Where one app ranks across keywords and countries, with trend where available.	— (adds coverage with an App Store Connect key)
compare_queries	How much two searches' results overlap, so you know whether a rank difference between them means anything.	—
suggest_keywords	What people actually type after a word, to check a keyword means what you assume. Never spends money.	—
low_star_reviews	Recent 1-3★ reviews for an app.	—
niche_report	Competitive report across a keyword set: top apps, a weakness score per rival, difficulty per keyword, gaps for your app.	— (adds volume with DataForSEO)
keyword_table	Your saved keyword list with current rank, difficulty, trend and autocomplete depth.	— (adds volume with DataForSEO)
snapshot_save / snapshot_diff	Save a named before/after of a keyword set, then compare the two.	— (snapshot_save adds coverage with an App Store Connect key)
my_listing	Your own app's name, subtitle and private keywords field, per locale.	App Store Connect key
audit_keywords	Tests every word in your keywords field, and shows what people typing each word actually want.	App Store Connect key
compare_markets	The same audit across several storefronts, to choose which market to work on.	App Store Connect key
price_keywords	Search volume for a keyword list you already have, billed to your DataForSEO account.	DataForSEO

Without the credential it needs, a tool returns a labelled unavailable saying what to set, rather than an error. Both credentials are set through environment variables:

• App Store Connect (free): ASC_API_ISSUER_ID and ASC_API_KEY_ID — setup.
• DataForSEO (paid, us only): DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD — costs and limits.

When a call fails instead, the error says why: see Rate limits & errors.

What leaves your machine

Requests to Apple's public App Store endpoints — search, lookup, autocomplete, reviews — which are what answer the tool calls. Worth knowing: audit_keywords sends each comma-separated entry of your private keywords field (up to 30) to Apple as a probe, because measuring whether a word works means asking the store for it. It goes to two endpoints, not one: search, and — unless you pass suggestions: false — autocomplete. compare_markets runs that audit once per storefront, up to eight, reading whichever localisation each storefront resolves to. How much of your listing that reaches depends on how localised your app is: a fully localised one sends up to eight different keyword fields, plus anchors from eight localised names and subtitles; an app with a single localisation sends that one field eight times, because Apple serves the primary locale wherever a localisation is missing. It never asks autocomplete, which it turns off deliberately.

Then two paths you have to switch on yourself, by setting the credentials above:

• DataForSEO, for keyword volume: sends the app ids being priced through, a country/language pair, and -- since 0.3.0 -- the keyword text itself, because naming keywords to the vendor is how a term outside an app's free top-50 window gets priced at all. The apps are the competitors a report found, which can include YOUR app when it ranks for those keywords: nothing excludes it. (This said "never your app, never your keywords" until 2026-09-07 -- true before 0.3.0, false the moment by-name pricing shipped.)
• App Store Connect (api.appstoreconnect.apple.com, a third Apple host beside the public itunes.apple.com and search.itunes.apple.com), to read your own listing text: a request signed with your own .p8 key. Five tools reach it -- my_listing, audit_keywords and compare_markets by their nature, plus keyword_ranks (whose coverage defaults on, so pass coverage: false to keep it local) and snapshot_save (which records coverage with no flag to turn it off). Apple returns data only for apps that key can see, but that limits what comes BACK, not what goes out: the request carries whichever app id you asked about, and for anyone else's app it returns nothing and coverage is silently absent.

Before any of that, the recommended npx -y @asolens/mcp asks the npm registry for the package each time your assistant starts the server -- that is npx, not ASOLens.

There is no telemetry. Your installId is sent nowhere, and vendor results are never pooled into a shared cache — they stay on your machine, tied to the account that paid for them. Nothing is sent about you except what a tool call asks for -- which, for audit_keywords and compare_markets, includes words read from your own listing rather than typed by you.

Known limitations

• App Store (iOS) only. No Google Play data.
• Keyword search volume is us only, and needs your own DataForSEO account. DataForSEO's Apple data covers the United States alone, and every lookup is billed to you. Every other signal works in all 17 storefronts.
• suggest_keywords never buys volume. No vendor sells volume for a bare App Store keyword. It only shows prices another tool already bought on any of the last 7 UTC days.
• Your App Store Connect listing is read once per server process. Restart the server after a release to see the new version.

Daily rank tracking: not open yet

A hosted service that checks your keywords every night from one fixed address and keeps the history, so you can see movement without running anything. It runs today for the author's own two apps. If you would use it, email [e-mail] with your app and roughly how many keywords and storefronts. Those emails decide whether it opens.

Questions, bugs and suggestions go to the same address.