# @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`](https://www.npmjs.com/package/@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:

```json
{
  "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:

```sh
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:

```text
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:

```text
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](https://github.com/modelcontextprotocol/inspector) can launch the published package and call its tools directly:

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

## Running from source

```sh
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:

```sh
npm test
npm run check
npm run build
```

## Agent skill

The repository includes a concise [Agent Skills](https://agentskills.io) 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:

```sh
# 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](LICENSE)