@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