# App Store MCP

![](screenshots/appstore.png)

A Model Context Protocol (MCP) server for interacting with Apple's App Store. This tool enables querying app information, searching the App Store, discovering trending apps, and retrieving app metadata through a standardized interface.

## Features

### App Search
- Search apps by name or keyword
- Filter by country/region
- Configurable result limits

### App Details
- Get comprehensive app information by ID
- Retrieve app metadata (description, version, ratings)
- Access pricing and availability info

### Trending Apps
- Discover top free, paid, and grossing apps
- Filter by platform (iPhone, iPad, Mac, Apple TV)
- Filter by category (Games, Productivity, etc.)
- Region-specific charts

### Screenshots
- Get iPhone and iPad screenshot URLs
- Useful for app previews and analysis

### Release Information
- Original release date
- Latest version release date
- Current version number

## Installation

### Claude Code

```bash
claude mcp add appstore-mcp -- npx appstore-mcp
```

### Manual Configuration

Add to your MCP config:

```json
{
  "mcpServers": {
    "appstore-mcp": {
      "command": "npx",
      "args": ["appstore-mcp"]
    }
  }
}
```

Or run locally:

```json
{
  "mcpServers": {
    "appstore-mcp": {
      "command": "node",
      "args": ["/path/to/appstore-mcp/dist/index.js"]
    }
  }
}
```

## Usage

### Available Tools

#### Search
- `search_apps` - Search for apps by name or keyword
  - `query`: Search term (required)
  - `country`: Country code (default: US)
  - `limit`: Max results (default: 25)

#### App Information
- `get_app_info` - Get information about an app by ID
  - `appId`: App Store ID (required)
  - `country`: Country code (default: US)
  - `include`: What info to return (default: basic)
    - `basic` - Name, artist, icon, price, rating
    - `full` - All details including description
    - `release` - Release dates and version info
    - `screenshots` - iPhone and iPad screenshot URLs

#### Trending
- `get_trending_apps` - Get top/trending apps
  - `platform`: iphone, ipad, mac, or tv (default: iphone)
  - `pricingType`: free, paid, or grossing (default: free)
  - `country`: Country code (default: US)
  - `categoryId`: Category ID to filter (optional)
  - `limit`: Max results (default: 25)

### Available Resources

Static reference data accessible via MCP resources:

- `appstore://countries` - List of all App Store country codes
- `appstore://categories` - App Store categories with IDs
- `appstore://platforms` - Supported platforms
- `appstore://pricing-types` - Pricing types (free, paid, grossing)

## Example Queries

Ask Claude things like:

- "Search for weather apps"
- "Get details for app ID 389801252"
- "Show top grossing games in Japan"
- "When was Spotify released?"
- "Get screenshots for the Twitter app"
- "List trending productivity apps on iPad"

## Category IDs

Common category IDs for filtering trending apps:

| ID | Category |
|----|----------|
| 6014 | Games |
| 6007 | Productivity |
| 6005 | Social Networking |
| 6016 | Entertainment |
| 6015 | Finance |
| 6008 | Photo & Video |
| 6017 | Education |
| 6013 | Health & Fitness |
| 6012 | Lifestyle |
| 6011 | Music |

## API Reference

This MCP server uses the following Apple APIs:

- **iTunes Search API** - App search and lookup
- **iTunes RSS Feed** - Top charts and trending apps

No authentication required - these are public APIs.

## Error Handling

The server provides detailed error messages for:
- App not found
- Invalid parameters
- Network errors
- API rate limits

## License

MIT