# App Store MCP Server

An MCP server for searching the App Store, checking keyword rankings, analyzing competition, and tracking trends — powered by a native macOS binary for fast, direct access to App Store APIs.

## Requirements

- macOS 26+ (Apple Silicon)

## Quick Start

### Install via uvx (recommended)

```bash
uvx appstore-mcp-server
```

This downloads the native binary on first run and starts the MCP server. No persistent installation needed.

### Install via pip

```bash
pip install appstore-mcp-server
appstore-mcp-server
```

### Download binary directly

Download the latest release from [GitHub Releases](https://github.com/drewster99/appstore-mcp-server/releases), extract, and run:

```bash
tar xzf appstore-*-macos-arm64.tar.gz
./appstore --mcp
```

## Claude Code Setup

Register as an MCP server:

```bash
claude mcp add --scope user --transport stdio -- appstore-mcp-server uvx appstore-mcp-server
```

Or with the binary directly:

```bash
claude mcp add --scope user --transport stdio -- appstore-mcp-server /path/to/appstore --mcp
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `version` | Get the server version |
| `search_apps` | iTunes Search API with attribute/genre filtering |
| `search_ranked` | MZStore API — results match actual App Store rankings |
| `lookup_app` | Look up an app by ID, bundle ID, or App Store URL |
| `top_charts` | Current top chart rankings (free, paid, grossing) |
| `find_app_rank` | Check where an app ranks for a keyword |
| `check_app_rankings` | Check an app's rank across auto-generated keywords |
| `analyze_keyword` | Competitive analysis with competitiveness score |
| `app_competitors` | Find an app's top competitors |
| `compare_keywords` | Compare competitiveness across multiple keywords |
| `discover_trending` | Discover trending categories from new chart entries |

Most tools support a `verbosity` parameter (`compact`, `full`, or `complete`) and a `storefront` parameter (two-letter country code, default: US).

## CLI Usage

The binary also works as a standalone CLI tool:

```bash
# Search for apps
./appstore search "weather app"

# Look up a specific app
./appstore lookup --id 6443547966

# Check keyword rankings for your app
./appstore ranks --id 6443547966 --keywords "weather,forecast,rain"

# Top charts
./appstore top --chart free --genre 6001

# Analyze keyword competition
./appstore analyze "photo editor"
```

Run `./appstore help` for full CLI documentation.

## Building from Source

```bash
git clone https://github.com/drewster99/appstore-mcp-server.git
cd appstore-mcp-server
```

Open `appstore.xcodeproj` in Xcode and build, or:

```bash
xcodebuild build \
    -project appstore.xcodeproj \
    -target appstore \
    -configuration Release \
    -arch arm64
```

The binary will be in `build/Release/appstore`.

## Architecture

See [CLAUDE.md](CLAUDE.md) for details on the dual-API architecture (MZStore for rankings, iTunes Search for metadata).

## License

MIT
