appstore-api-mcp 1.0.0

package/.env.example

@@ -0,0 +1,20 @@
+# App Store Connect API credentials
+# Create a key at: App Store Connect → Users and Access → Integrations → App Store Connect API
+# See docs/SETUP.md for the full walkthrough.
+
+# Key ID (short alphanumeric, shown next to the key)
+ASC_KEY_ID=
+
+# Issuer ID (UUID, shown at the top of the Integrations page)
+ASC_ISSUER_ID=
+
+# Provide the .p8 private key ONE of these three ways:
+
+# 1) Absolute path to the downloaded .p8 file (simplest)
+ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
+
+# 2) ...or the raw PEM contents (keep the newlines)
+# ASC_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
+
+# 3) ...or base64 of the .p8 file (no newline headaches):  base64 -i AuthKey_XXXX.p8
+# ASC_PRIVATE_KEY_BASE64=

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-06-02
+
+### Added
+- Initial release.
+- App browsing: `list_apps`, `get_app`.
+- App info localizations (name, subtitle, privacy policy): list / update / create.
+- App Store versions: list / create.
+- Version localizations (description, keywords, promotional text, what's-new, URLs): list / get / update / create.
+- Screenshots: list/create sets, list/upload/delete screenshots (full reserve→upload→commit flow).
+- `audit_apps` — fleet-wide ASO/listing health check across all apps, read-only, with an account summary.
+- Dry-run mode (`dryRun: true`) on the update tools — preview a field-by-field diff with length/limit checks before writing.
+- `raw_request` escape hatch covering the entire App Store Connect API.
+- ES256 JWT auth with three key-input methods: file path, raw PEM, base64.
+- Multi-client setup guide (`docs/CLIENTS.md`) — Claude, Cursor, Cline, Windsurf, VS Code, Zed, Continue, and custom agents.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sviatoslav Fil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# App Store Connect MCP
+
+An [MCP](https://modelcontextprotocol.io) server that lets **any AI agent** read
+and edit your **App Store Connect** apps in plain language — keywords,
+descriptions, titles, subtitles, promotional text, what's-new, screenshots,
+versions — plus a raw-request tool that reaches the **entire**
+[App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi).
+
+> Ask things like *"update the keywords for my app to X, Y, Z"*,
+> *"show the English description for MyApp"*, or
+> *"upload these screenshots to the 6.7-inch set"* — the agent calls the right tools.
+
+- 🤖 **Works with any MCP client** — Claude Code/Desktop, Cursor, Cline, Windsurf, VS Code (agent mode), Zed, Continue, and custom agents on the MCP SDKs. Standard stdio server, no client-specific code. → [docs/CLIENTS.md](docs/CLIENTS.md)
+- ✅ **One-line install** via `npx` — no clone, no build
+- ✅ **Credentials stay on your machine** — calls go straight to Apple, nothing is proxied
+- ✅ **Slim, well-described tool set** + a `raw_request` escape hatch for the whole API
+- 🛡️ **Dry-run mode** — preview any metadata change (old→new + length checks) before writing
+- 🚀 **Fleet audit** — one call health-checks **all** your apps for ASO gaps (built for indies with many apps)
+- ✅ MIT licensed, actively maintained
+
+---
+
+## Table of contents
+
+- [Quick start](#quick-start)
+- [Supported clients](#supported-clients) → full guide in [docs/CLIENTS.md](docs/CLIENTS.md)
+- [Getting your API key](#getting-your-api-key) → full guide in [docs/SETUP.md](docs/SETUP.md)
+- [Configuration](#configuration)
+- [Tools](#tools) → full reference in [docs/TOOLS.md](docs/TOOLS.md)
+- [Common workflows](#common-workflows)
+- [Security](#security) → details in [docs/SECURITY.md](docs/SECURITY.md)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+
+---
+
+## Quick start
+
+**Requirements:** Node.js ≥ 18 and an Apple Developer account with an
+[App Store Connect API key](#getting-your-api-key).
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add appstore-api \
+  --env ASC_KEY_ID=YOUR_KEY_ID \
+  --env ASC_ISSUER_ID=YOUR_ISSUER_ID \
+  --env ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8 \
+  -- npx -y appstore-api-mcp
+```
+
+Add `--scope user` to make it available in **every** project (default is the
+current project only).
+
+### Any other MCP client (Cursor, Cline, Windsurf, VS Code, Zed, Continue, …)
+
+Almost every client uses this same block (Claude Desktop config path:
+`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "appstore-api": {
+      "command": "npx",
+      "args": ["-y", "appstore-api-mcp"],
+      "env": {
+        "ASC_KEY_ID": "YOUR_KEY_ID",
+        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
+        "ASC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey_XXXXXXXXXX.p8"
+      }
+    }
+  }
+}
+```
+
+Restart the client, then ask it to *"list my App Store apps"* to confirm it works.
+
+---
+
+## Supported clients
+
+This is a standard stdio MCP server — it works with **any MCP-compatible agent**.
+The command (`npx -y appstore-api-mcp`) and the three `ASC_*` env vars are always
+the same; only each client's config format/location differs.
+
+| Client | Where to configure |
+| --- | --- |
+| **Claude Code** | `claude mcp add …` (see above) |
+| **Claude Desktop** | `claude_desktop_config.json` → `mcpServers` |
+| **Cursor** | `.cursor/mcp.json` → `mcpServers` |
+| **Cline** (VS Code) | `cline_mcp_settings.json` → `mcpServers` |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` → `mcpServers` |
+| **VS Code** (agent mode) | `.vscode/mcp.json` → `servers` (note: not `mcpServers`) |
+| **Zed** | `settings.json` → `context_servers` |
+| **Continue** | `~/.continue/config.yaml` → `mcpServers` |
+| **Custom agent** (MCP SDK / Agents SDK / LangChain) | spawn the stdio command with the env vars |
+
+Copy-paste config snippets for each are in **[docs/CLIENTS.md](docs/CLIENTS.md)**.
+
+---
+
+## Getting your API key
+
+1. Go to **[App Store Connect](https://appstoreconnect.apple.com) → Users and Access → Integrations → App Store Connect API**.
+2. Click **+** to generate a key. Give it a name and the **least privilege** role
+   you need — **App Manager** is enough to edit metadata, keywords and
+   screenshots. (Avoid **Admin** unless you truly need it.)
+3. Note the **Issuer ID** (top of the page) and the **Key ID** (next to the key).
+4. **Download the `.p8` file** — you can only download it once. Store it somewhere safe.
+
+Full walkthrough with screenshots-worth of detail: **[docs/SETUP.md](docs/SETUP.md)**.
+
+---
+
+## Configuration
+
+All configuration is via environment variables.
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `ASC_KEY_ID` | yes | The key's ID (short alphanumeric) |
+| `ASC_ISSUER_ID` | yes | The issuer UUID from the Integrations page |
+| `ASC_PRIVATE_KEY_PATH` | one of these three | Absolute path to the `.p8` file |
+| `ASC_PRIVATE_KEY` | one of these three | The raw PEM contents of the key |
+| `ASC_PRIVATE_KEY_BASE64` | one of these three | Base64 of the `.p8` (`base64 -i AuthKey.p8`) — easiest for env vars |
+
+See [.env.example](.env.example) for a copy-paste template.
+
+---
+
+## Tools
+
+A compact set of high-level tools, plus `raw_request` for everything else.
+Full parameter reference: **[docs/TOOLS.md](docs/TOOLS.md)**.
+
+| Tool | What it does |
+| --- | --- |
+| `list_apps` / `get_app` | Browse your apps |
+| `list_app_infos` | Find the record holding name/subtitle/privacy localizations |
+| `list_app_info_localizations` | Read name, subtitle, privacy policy per locale |
+| `update_app_info_localization` | Update **name, subtitle, privacy policy** |
+| `create_app_info_localization` | Add a new locale's name/subtitle |
+| `list_app_store_versions` | List versions and their states |
+| `create_app_store_version` | Start a new version to prepare for submission |
+| `list_app_store_version_localizations` | Read description/keywords/etc. per locale |
+| `get_app_store_version_localization` | Read one locale's listing copy |
+| `update_app_store_version_localization` | Update **keywords, description, promo text, what's-new, URLs** |
+| `create_app_store_version_localization` | Add a new locale to a version |
+| `list_screenshot_sets` / `create_screenshot_set` | Manage per-device screenshot sets |
+| `list_screenshots` / `upload_screenshot` / `delete_screenshot` | Manage screenshots (upload handles the full reserve→upload→commit flow) |
+| 🚀 `audit_apps` | **Fleet health check** — scan all (or selected) apps for missing subtitle/keywords/description, under-used keyword field, single-locale listings, missing screenshots, and more. Read-only. |
+| `raw_request` | Any method/path against the API — previews, pricing, TestFlight, IAP, reviews, analytics, sales reports, … |
+
+> 🛡️ **Dry-run:** the `update_*` tools accept `dryRun: true` — they return a field-by-field
+> diff (old → new) with length/limit checks and **write nothing**. Drop the flag to apply.
+
+---
+
+## Common workflows
+
+### Update keywords or description
+
+1. `list_apps` → get the app id
+2. `list_app_store_versions` (filter `PREPARE_FOR_SUBMISSION`) → the editable version id
+3. `list_app_store_version_localizations` → the locale's localization id
+4. `update_app_store_version_localization` with `keywords` and/or `description`
+
+In practice you just ask: *"set the keywords for MyApp to a, b, c"* and the model
+chains these for you.
+
+### Update the app name or subtitle
+
+`list_app_infos` → `list_app_info_localizations` → `update_app_info_localization`.
+
+### Upload screenshots
+
+`list_app_store_version_localizations` → `list_screenshot_sets`
+(or `create_screenshot_set`) → `upload_screenshot` with an absolute image path.
+
+### Audit your whole portfolio (the indie superpower)
+
+Just ask: *"Audit all my apps for ASO gaps."* One `audit_apps` call returns a
+ranked report — which apps are missing keywords, subtitles, descriptions, or
+under-using the 100-char keyword field — plus an account-wide summary. Add
+`checkScreenshots: true` to also flag apps with no screenshots.
+
+```jsonc
+// returns { summary: { appsAudited, appsWithIssues, issuesByType, … }, findings: [ … ] }
+{ "name": "audit_apps", "arguments": { "checkScreenshots": false } }
+```
+
+### Preview before you write (dry-run)
+
+Every `update_*` tool takes `dryRun: true`. You get the exact diff and length
+checks, and **nothing is written** — so you (or the model) can confirm first:
+
+```jsonc
+{ "name": "update_app_store_version_localization",
+  "arguments": { "localizationId": "…", "keywords": "todo,tasks,planner", "dryRun": true } }
+// → { dryRun:true, changes:[{ field:"keywords", from:"…", to:"…", newLength:18, limit:100, exceedsLimit:false }], warnings:[] }
+```
+
+### Anything else
+
+Use `raw_request`, e.g. read customer reviews:
+`GET /apps/{id}/customerReviews`. The whole API surface is reachable this way.
+
+---
+
+## Field limits (enforced by Apple)
+
+| Field | Limit |
+| --- | --- |
+| App name | 30 chars |
+| Subtitle | 30 chars |
+| Keywords (comma-separated, combined) | 100 chars |
+| Promotional text | 170 chars |
+| Description / What's New | 4000 chars |
+
+Metadata only **saves on a version in an editable state** (e.g.
+`PREPARE_FOR_SUBMISSION`) — except **promotional text**, which can change live.
+Edits go to the **draft**; they go public only after you submit and Apple approves.
+
+---
+
+## Security
+
+- Your API key is **powerful** — it can rewrite your live store listings. Treat it like a password.
+- Credentials are read from env vars and used **only** to talk to Apple directly. Nothing is sent anywhere else.
+- **Never commit your `.p8` or credentials.** This repo's `.gitignore` and npm `files` whitelist are set up to prevent that.
+- Use a **dedicated, least-privilege key** (App Manager), and revoke it anytime in App Store Connect.
+
+More: **[docs/SECURITY.md](docs/SECURITY.md)**.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `ASC_KEY_ID is required` etc. | An env var is missing — recheck your config. |
+| `401`/`403` errors | Wrong issuer/key id, wrong `.p8`, or the key's role lacks permission. |
+| `409` on metadata update | The version isn't in an editable state — create/select a `PREPARE_FOR_SUBMISSION` version. |
+| `npx` can't find the package | Ensure Node ≥ 18 and that the package name is published/correct. |
+| Tools don't appear | MCP servers load at client startup — restart the client / start a new session. |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/fil-technology/appstore-api-mcp.git
+cd appstore-api-mcp
+npm install
+cp .env.example .env   # fill in your credentials
+node src/index.js      # runs the server on stdio (Ctrl-C to stop)
+```
+
+The server is plain ES modules, no build step. Source:
+- `src/index.js` — tool definitions + MCP wiring
+- `src/client.js` — JWT (ES256) auth, request/paging helpers, asset upload
+
+## License
+
+MIT © Sviatoslav Fil — see [LICENSE](LICENSE).

package/docs/CLIENTS.md

@@ -0,0 +1,167 @@
+# Using with different MCP clients
+
+This is a standard [Model Context Protocol](https://modelcontextprotocol.io)
+server over **stdio** — it works with **any** MCP-compatible agent, not just
+Claude. The server itself contains nothing client-specific; only the *config
+format and file location* differ per client.
+
+Everything below runs the same command:
+
+```
+npx -y appstore-api-mcp
+```
+
+with these three env vars (see [SETUP.md](SETUP.md) to get them):
+
+| Variable | Value |
+| --- | --- |
+| `ASC_KEY_ID` | your key id |
+| `ASC_ISSUER_ID` | your issuer id |
+| `ASC_PRIVATE_KEY_PATH` | absolute path to your `.p8` (or use `ASC_PRIVATE_KEY` / `ASC_PRIVATE_KEY_BASE64`) |
+
+> Tip: most clients use the identical `{ "mcpServers": { … } }` block shown for
+> Claude Desktop. Where a client differs (VS Code, Zed), it's called out below.
+
+---
+
+## Claude Code (CLI)
+
+```bash
+claude mcp add appstore-api \
+  --scope user \
+  --env ASC_KEY_ID=YOUR_KEY_ID \
+  --env ASC_ISSUER_ID=YOUR_ISSUER_ID \
+  --env ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey.p8 \
+  -- npx -y appstore-api-mcp
+```
+
+## Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) /
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "appstore-api": {
+      "command": "npx",
+      "args": ["-y", "appstore-api-mcp"],
+      "env": {
+        "ASC_KEY_ID": "YOUR_KEY_ID",
+        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
+        "ASC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey.p8"
+      }
+    }
+  }
+}
+```
+
+## Cursor
+
+Project-level `.cursor/mcp.json` (or global `~/.cursor/mcp.json`) — same shape:
+
+```json
+{
+  "mcpServers": {
+    "appstore-api": {
+      "command": "npx",
+      "args": ["-y", "appstore-api-mcp"],
+      "env": {
+        "ASC_KEY_ID": "YOUR_KEY_ID",
+        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
+        "ASC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey.p8"
+      }
+    }
+  }
+}
+```
+
+## Cline (VS Code extension)
+
+Open the Cline MCP settings (`cline_mcp_settings.json`) and add the same
+`mcpServers` entry as above.
+
+## Windsurf (Codeium)
+
+`~/.codeium/windsurf/mcp_config.json` — same `mcpServers` shape as Claude Desktop.
+
+## VS Code (native MCP / Copilot agent mode)
+
+VS Code uses a `servers` key (note: **not** `mcpServers`). Project file
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "appstore-api": {
+      "command": "npx",
+      "args": ["-y", "appstore-api-mcp"],
+      "env": {
+        "ASC_KEY_ID": "YOUR_KEY_ID",
+        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
+        "ASC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey.p8"
+      }
+    }
+  }
+}
+```
+
+## Zed
+
+In `settings.json`, Zed uses `context_servers` with a nested `command` object:
+
+```json
+{
+  "context_servers": {
+    "appstore-api": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "appstore-api-mcp"],
+        "env": {
+          "ASC_KEY_ID": "YOUR_KEY_ID",
+          "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
+          "ASC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey.p8"
+        }
+      }
+    }
+  }
+}
+```
+
+## Continue
+
+In `~/.continue/config.yaml`:
+
+```yaml
+mcpServers:
+  - name: appstore-api
+    command: npx
+    args: ["-y", "appstore-api-mcp"]
+    env:
+      ASC_KEY_ID: YOUR_KEY_ID
+      ASC_ISSUER_ID: YOUR_ISSUER_ID
+      ASC_PRIVATE_KEY_PATH: /absolute/path/to/AuthKey.p8
+```
+
+## Any other MCP client / custom agent
+
+Point your client at a stdio server with:
+
+- **command:** `npx`
+- **args:** `["-y", "appstore-api-mcp"]`
+- **env:** the three `ASC_*` variables
+
+Or, if your client launches binaries by path, install globally
+(`npm i -g appstore-api-mcp`) and run `appstore-api-mcp` directly. For SDK-based
+agents (e.g. the Python/TypeScript MCP SDKs, OpenAI Agents SDK, LangChain MCP
+adapters), spawn the same stdio command and pass the env vars through.
+
+---
+
+### Notes that apply to every client
+
+- The server speaks MCP over **stdio** — no ports, no network server to manage.
+- It needs **Node.js ≥ 18** on the machine running the client.
+- Credentials are read from the env you supply and used **only** to call Apple directly.
+- After editing a client's config, **restart the client** (or start a new session)
+  so it picks up the server.

package/docs/SECURITY.md

@@ -0,0 +1,57 @@
+# Security
+
+This server talks to Apple on your behalf using an App Store Connect API key.
+That key can **read and modify your live App Store presence**. Treat it with the
+same care as a password.
+
+## What the key can do
+
+Depending on the role you assign, the key can edit metadata and keywords, upload
+screenshots, manage TestFlight, change pricing, respond to reviews, and download
+sales/finance data. Scope it down.
+
+## Principle of least privilege
+
+- Create a **dedicated key** just for this server — don't reuse one.
+- Give it the **lowest role** that covers your tasks. **App Manager** is enough for
+  metadata, keywords, and screenshots. Avoid **Admin** unless you truly need it.
+- You can **revoke** the key at any time in App Store Connect → Users and Access →
+  Integrations. Revoking is instant and breaks only this integration.
+
+## Where credentials live
+
+- Credentials are read from **environment variables** at startup.
+- They are used **only** to mint a short-lived (≤20 min) JWT and call
+  `api.appstoreconnect.apple.com` **directly**. Nothing is proxied through any
+  third party, and nothing is logged to disk by this server.
+- The JWT is held in memory and regenerated as needed.
+
+## Never commit secrets
+
+This project is set up to keep secrets out of git and npm:
+
+- `.gitignore` excludes `secrets/`, `*.p8`, `.env`, `*.key`.
+- `package.json` uses a `files` allow-list, so **only** `src/`, docs, README,
+  LICENSE, and `.env.example` are published to npm — even if a key sits in the
+  folder, `npm publish` won't include it.
+
+**Before committing or publishing, always verify:**
+
+```bash
+git status                 # no .p8, no .env, no secrets/
+npm pack --dry-run         # review the file list — there must be NO key files
+```
+
+If a key is ever exposed (committed, pasted, shared), **revoke it immediately**
+and generate a new one — that's a 60-second operation and the only safe response.
+
+## Handling the .p8 file
+
+- Store it outside any repo (e.g. `~/.appstoreconnect/`), `chmod 600`.
+- Prefer `ASC_PRIVATE_KEY_PATH`. For containers/CI where files are awkward, use
+  `ASC_PRIVATE_KEY_BASE64` injected as a secret — not committed to the repo.
+
+## Reporting a vulnerability
+
+Found a security issue in this server? Please open a private report / security
+advisory on the GitHub repository rather than a public issue.

package/docs/SETUP.md

@@ -0,0 +1,105 @@
+# Setup guide
+
+Step-by-step from zero to a working server.
+
+## 1. Prerequisites
+
+- **Node.js ≥ 18** — check with `node --version`. Install from [nodejs.org](https://nodejs.org) or `brew install node`.
+- An **Apple Developer Program** membership with access to App Store Connect.
+- A role that can create API keys: **Account Holder** or **Admin** creates the key;
+  the key itself can carry a lower role (see below).
+
+## 2. Create an App Store Connect API key
+
+1. Sign in to [App Store Connect](https://appstoreconnect.apple.com).
+2. Go to **Users and Access** → **Integrations** tab → **App Store Connect API**.
+3. Copy the **Issuer ID** shown near the top — this is your `ASC_ISSUER_ID`
+   (a UUID like `12345678-90ab-cdef-1234-567890abcdef`).
+4. Click the **+** button to create a new key.
+   - **Name:** something like `mcp-metadata`.
+   - **Access (role):** choose the **least privilege** that covers your use:
+     - **App Manager** — edit metadata, keywords, screenshots, versions, TestFlight. ✅ Recommended.
+     - **Developer** — narrower; may not allow all edits.
+     - **Admin** — full control. Only if you genuinely need it.
+5. Click **Generate**. You'll now see the key listed with a **Key ID** — that's your `ASC_KEY_ID`.
+6. Click **Download API Key** to get the `AuthKey_XXXXXXXXXX.p8` file.
+   > ⚠️ You can only download this **once**. Save it somewhere safe and backed up.
+   > If you lose it, revoke the key and create a new one.
+
+## 3. Store the key safely
+
+Pick a stable location outside any git repo, e.g.:
+
+```bash
+mkdir -p ~/.appstoreconnect
+mv ~/Downloads/AuthKey_XXXXXXXXXX.p8 ~/.appstoreconnect/
+chmod 600 ~/.appstoreconnect/AuthKey_XXXXXXXXXX.p8
+```
+
+## 4. Add the server to your MCP client
+
+### Claude Code
+
+```bash
+claude mcp add appstore-connect \
+  --scope user \
+  --env ASC_KEY_ID=YOUR_KEY_ID \
+  --env ASC_ISSUER_ID=YOUR_ISSUER_ID \
+  --env ASC_PRIVATE_KEY_PATH=$HOME/.appstoreconnect/AuthKey_XXXXXXXXXX.p8 \
+  -- npx -y appstore-api-mcp
+```
+
+`--scope user` makes it available in all projects. Drop it to scope to the current project only.
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "appstore-connect": {
+      "command": "npx",
+      "args": ["-y", "appstore-api-mcp"],
+      "env": {
+        "ASC_KEY_ID": "YOUR_KEY_ID",
+        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
+        "ASC_PRIVATE_KEY_PATH": "/Users/you/.appstoreconnect/AuthKey_XXXXXXXXXX.p8"
+      }
+    }
+  }
+}
+```
+
+Then fully quit and reopen Claude Desktop.
+
+### Cursor / Windsurf / other clients
+
+Use the same `command` / `args` / `env` shape in that client's MCP settings file.
+
+## 5. Verify
+
+Start a new chat / session and ask: **"List my App Store Connect apps."**
+You should get your app list back. If not, see [Troubleshooting](#troubleshooting) below.
+
+## Alternative: passing the key without a file path
+
+If your environment makes file paths awkward (containers, CI), base64-encode the key:
+
+```bash
+base64 -i AuthKey_XXXXXXXXXX.p8     # macOS
+base64 -w0 AuthKey_XXXXXXXXXX.p8    # Linux
+```
+
+Then set `ASC_PRIVATE_KEY_BASE64` instead of `ASC_PRIVATE_KEY_PATH`.
+
+## Troubleshooting
+
+- **`401 NOT_AUTHORIZED` / `403`** — issuer ID or key ID doesn't match the `.p8`,
+  or the key's role lacks permission for that action. Double-check all three.
+- **`ASC_*_is required`** — an env var didn't reach the process. In Claude Desktop,
+  confirm the JSON is valid and you restarted the app.
+- **`409 CONFLICT` on a metadata update** — the App Store version isn't editable.
+  Create or select a version in `PREPARE_FOR_SUBMISSION` state.
+- **Token/clock errors** — JWTs are time-based; make sure your system clock is correct.
+- **`npx` fails to resolve the package** — verify Node ≥ 18 and the published package name.