# App Store Connect MCP Server

An MCP (Model Context Protocol) server that lets Claude talk to the [App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi): app metadata, builds & releases, sales/analytics reports, and Game Center leaderboards/achievements.

## 1. Get App Store Connect API credentials

1. Go to [App Store Connect](https://appstoreconnect.apple.com) → **Users and Access** → **Integrations** → **App Store Connect API**.
2. Click **Generate API Key**. You need Admin or App Manager access (Admin recommended, since sales reports and Game Center need broader access).
3. Download the `.p8` private key immediately — Apple only lets you download it once.
4. Note the **Issuer ID** (top of the page) and the **Key ID** (next to your new key).
5. For sales reports, also grab your **Vendor Number** from **Payments and Financial Reports**.

## 2. Configure

```bash
npm install
cp .env.example .env
```

Edit `.env` with your Issuer ID, Key ID, the path to your `.p8` file, and (optionally) your vendor number.

## 3. Build

```bash
npm run build
```

## 4. Connect it to Claude

**Claude Code:**

```bash
claude mcp add appstore-connect -- node "/absolute/path/to/AppStoreConnectMCP/build/index.js"
```

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "appstore-connect": {
      "command": "node",
      "args": ["/absolute/path/to/AppStoreConnectMCP/build/index.js"],
      "env": {
        "ASC_ISSUER_ID": "...",
        "ASC_KEY_ID": "...",
        "ASC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey_XXXX.p8",
        "ASC_VENDOR_NUMBER": "..."
      }
    }
  }
}
```

(If you use a `.env` file instead, the server loads it automatically from the project's own install directory, regardless of the working directory it's launched from — so either approach works for GUI apps too.)

## Tools

**Apps**
- `list_apps`, `get_app`
- `list_app_store_versions`, `get_app_store_version`

**Builds & releases**
- `list_builds`, `get_build`, `expire_build`
- `submit_version_for_review`

**Sales & analytics reports**
- `download_sales_report` — downloads and decodes SALES/SUBSCRIPTION/etc. reports (requires `ASC_VENDOR_NUMBER`)

**Game Center**
- `get_game_center_detail`
- `list_game_center_leaderboards`, `create_game_center_leaderboard`, `delete_game_center_leaderboard`, `list_game_center_leaderboard_versions`, `create_game_center_leaderboard_localization`
- `list_game_center_achievements`, `create_game_center_achievement`, `delete_game_center_achievement`, `list_game_center_achievement_versions`, `create_game_center_achievement_localization`

**Escape hatch**
- `appstore_connect_request` — call any App Store Connect endpoint directly (method/path/query/body) for anything not covered above.

## Notes

- Tokens are generated per-request and cached for ~19 minutes (Apple's JWTs expire after 20).
- Game Center leaderboards and achievements use Apple's v2 API, which requires creating an initial "version" resource alongside the leaderboard/achievement — the create tools handle this automatically and return the version ID so you can immediately localize it.
- Never commit your `.p8` file or `.env` — both are gitignored.