@perttu/app-store-mcp

An MCP server for looking up apps, reviews, ratings, charts, in-app purchases, privacy details, and version history on Apple's App Store. It is built on @perttu/app-store-scraper and does not require an API key.

Requirements

• Node.js 20 or newer
• An MCP client that can launch local stdio servers

Setup

You do not need to install the package globally. Add this to your MCP client's server configuration:

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

Restart the client after changing its configuration. It should discover eleven tools whose names begin with app_store_.

If your client cannot find npx, replace npx with its absolute path. Run which npx on macOS or Linux, or where npx on Windows, to find it.

To install the executable yourself instead:

npm install --global @perttu/app-store-mcp

Then use app-store-mcp as the command and omit the arguments array.

Tools

Tool	What it returns
app_store_app	Full metadata for one app, addressed by track ID or bundle ID
app_store_search	Keyword search results, with pagination and an IDs-only option
app_store_list	Ranked App Store collections, optionally filtered by category
app_store_developer	Apps published by a developer
app_store_reviews	Recent or helpful reviews, up to page 10
app_store_ratings	Total rating count and the 1–5 star distribution
app_store_similar	Apps related to a given app
app_store_suggest	Autocomplete suggestions for a search term
app_store_privacy	Privacy labels and policy information
app_store_version_history	Previous versions, dates, and release notes
app_store_in_app_purchases	Top in-app purchase names and localized prices

Most tools accept a two-letter country code. The default is us. Tools backed by Apple's lookup and search APIs also accept a lang value such as en-us.

Every tool is read-only. Results are returned as both structured content and formatted JSON text, so they work with clients that support either response form.

Arguments

country is optional and defaults to us. Use a two-letter store code such as fi, gb, or jp; uppercase codes are accepted too. lang is an optional locale such as en-us.

Tool	Required	Optional
app_store_app	id or appId	country, lang, ratings
app_store_search	term	country, lang, num (1–200), page (from 1), idsOnly
app_store_list	—	country, lang, collection, category, num (1–200), fullDetail
app_store_developer	devId	country, lang
app_store_reviews	id or appId	country, lang, page (1–10), sort
app_store_ratings	id	country
app_store_similar	id or appId	country, lang
app_store_suggest	term	country
app_store_privacy	id	country
app_store_version_history	id	country
app_store_in_app_purchases	id	country

id, devId, and category are numeric. appId is the bundle identifier, for example com.apple.Pages.

The available collections are:

topmacapps                 topfreemacapps           topgrossingmacapps
toppaidmacapps             newapplications          newfreeapplications
newpaidapplications        topfreeapplications      topfreeipadapplications
topgrossingapplications    topgrossingipadapplications
toppaidapplications        toppaidipadapplications

Review sort is either mostRecent (the default) or mostHelpful. category is one of Apple's numeric App Store genre IDs; common values include games (6014), education (6017), productivity (6007), utilities (6002), and business (6000). The complete allowed set is included in the tool's input schema and exported as category from the package.

Example requests

The exact prompt is up to the client. These are representative:

Find the first five App Store results for "interval timer" in Finland.

Show the rating breakdown and recent reviews for app 553834731.

What data does app 284882215 say it collects?

app_store_list can fetch full metadata for every chart entry with fullDetail: true. That makes one additional App Store request per result, so use it with a small num value.

Checking the server

The MCP Inspector can launch the published package and call its tools directly:

npx @modelcontextprotocol/inspector npx -y @perttu/app-store-mcp

Running from source

git clone https://github.com/plahteenlahti/app-store-mcp.git
cd app-store-mcp
npm ci
npm run build
node dist/cli.js

The last command waits for MCP messages on stdin; it does not open an interactive prompt. For a local client configuration, point command at node and pass the absolute path to dist/cli.js in args.

Useful development commands:

npm test
npm run check
npm run build

Agent skill

The repository includes a concise Agent Skills workflow at skills/app-store-research. It teaches agents to choose the narrowest tool, reuse identifiers, and avoid unnecessarily large responses.

Codex and Claude Code discover it automatically while working in this repository through .agents/skills and .claude/skills. To use it in other projects, copy the canonical skill folder to your user skill directory:

# Codex
cp -R skills/app-store-research ~/.agents/skills/

# Claude Code
cp -R skills/app-store-research ~/.claude/skills/

Notes

This project reads public Apple endpoints. Apple can change those endpoints or apply rate limits without notice. The server deliberately does not cache or throttle requests; the calling client remains in control of when tools run.

This project is not affiliated with or endorsed by Apple Inc. App Store is a trademark of Apple Inc.

License

MIT