appstore-mcp

An MCP server, written in Rust, that exposes

the Apple App Store Connect API to AI agents. It covers the full product

lifecycle — apps & metadata, in-app purchases, subscriptions and their offers,

pricing & availability, App Store versions, App Review submission, TestFlight,

provisioning & signing, asset uploads, promoted purchases, customer reviews,

phased release, users & access, in-app events, Xcode Cloud, and analytics

reports — across 114 tools, and can reach *any* other App Store Connect

endpoint through two generic JSON:API tools.

Built on the official `rmcp` SDK over stdio.

📖 **Full tool reference → docs/TOOLS.md** — every tool's purpose

and parameters.

Every tool is labelled with MCP annotations, so a client can tell `list_apps`

from `remove_user`. You can serve only the domains you need (`ASC_TOOLS`) or only

the tools that cannot write (`ASC_READ_ONLY`) — see

Choosing which tools to serve.

Design: hybrid coverage

The App Store Connect API has hundreds of endpoints but is uniformly

JSON:API. Rather than a tool per endpoint, this server is

hybrid:

• Curated tools (112) for the common, multi-step, or error-prone workflows —

apps & metadata, IAPs, subscriptions & offers, versions, pricing, availability,

App Review submission, TestFlight, provisioning, asset uploads, promoted

purchases, customer reviews, phased release, users, in-app events, Xcode Cloud,

analytics reports, and custom product pages.

• Two generic escape-hatch tools — `appstore_request` and `appstore_list` —

that can call *any* endpoint with raw JSON:API documents.

Tools

See **docs/TOOLS.md** for each tool's description and parameters. Custom product page

images are uploaded with the existing `upload_app_screenshot` / `upload_app_preview` tools.

Install

Prebuilt binaries for macOS (universal), Linux (x86-64), and Windows (x86-64)

are attached to every GitHub Release.

Pick the channel for your client; all of them need credentials (see Credentials).

Claude Desktop — one-click bundle

Download `appstore-mcp.mcpb` from the latest release and open it with Claude Desktop

(Settings → Extensions → Install Extension…, or drag the file onto the window).

It prompts for your Issuer ID, Key ID, and .p8 key file. The bundle ships

all three platforms' binaries and selects the right one automatically.

Claude Code — plugin marketplace

/plugin marketplace add forgeopslabs/appstore-mcp
/plugin install appstore-mcp@forgeopslabs

The plugin launches the `appstore-mcp` binary from your `PATH`, so install it first —

download the binary for your OS from the latest release

and put it on your `PATH`, or `cargo install --git https://github.com/forgeopslabs/appstore-mcp`.

Set `ASC_ISSUER_ID`, `ASC_KEY_ID`, and `ASC_PRIVATE_KEY_PATH` in the environment you start

Claude Code from.

Codex

Codex configures MCP servers directly (no marketplace). With `appstore-mcp` on your `PATH`:

codex mcp add appstore \
  --env ASC_ISSUER_ID=... --env ASC_KEY_ID=... \
  --env ASC_PRIVATE_KEY_PATH=/path/AuthKey_XXXXXX.p8 \
  -- appstore-mcp

or in `~/.codex/config.toml`:

[mcp_servers.appstore]
command = "appstore-mcp"
args = []
env = { ASC_ISSUER_ID = "...", ASC_KEY_ID = "...", ASC_PRIVATE_KEY_PATH = "/path/AuthKey_XXXXXX.p8" }

MCP Registry

Published as `io.github.forgeopslabs/appstore-mcp` (metadata in

`server.json`) so any MCP-aware client can discover it.

From source

cargo build --release    # -> target/release/appstore-mcp

Credentials

Generate a Team Key in App Store Connect → *Users and Access → Integrations →

App Store Connect API*, and download the `.p8` file. Then set:

See `.env.example`. The server authenticates each request with a

short-lived ES256 JWT signed by your key (cached and refreshed automatically).

> The server starts even without credentials so a client can list its tools;

> tool calls then return an actionable configuration error until creds are set.

Choosing which tools to serve

A hundred tool definitions cost context in every session, and a client that sees

one flat list can't tell a read from a delete. Two knobs fix that:

ASC_TOOLS=core                     # 41 tools: generic, apps, versions, assets, testflight, submission
ASC_TOOLS=testflight,provisioning  # just what a build-distribution agent needs
ASC_READ_ONLY=1                    # 35 read-only tools; writes are withheld entirely

Groups: `generic`, `apps`, `iap`, `subscriptions`, `versions`, `pricing`,

`availability`, `submission`, `testflight`, `provisioning`, `assets`, `offers`,

`offer-codes`, `promotions`, `reviews`, `users`, `events`, `xcode-cloud`,

`analytics`, `custom-product-pages` — plus `all` and `core`. An unrecognised name

is warned about on stderr and serves nothing rather than quietly falling back to

everything.

In read-only mode `appstore_request` is kept but refuses any method other than

`GET`, so the escape hatch still reaches endpoints without a curated tool without

becoming a way around the restriction.

Every served tool advertises MCP annotations (`readOnlyHint`, `destructiveHint`,

`idempotentHint`), which clients use to decide what needs confirming. Nine tools

are marked destructive: the seven `delete_*`/`remove_*` tools, `expire_build`,

`disable_bundle_id_capability`, and `appstore_request` (which can reach any

`DELETE` endpoint).

Tuning

Defaults are chosen so a tool call can't hang and a single response can't swamp

an agent's context. All of these are optional.

Retries. A `429` is replayed for any method, since Apple rejected the request

without applying it. A `5xx` or a mid-flight timeout is replayed only for

`GET`/`PATCH`/`PUT`/`DELETE` — never `POST`, which could otherwise create a

duplicate resource (and Apple permanently reserves identifiers like a product

ID). Backoff is exponential with jitter and honours `Retry-After`.

Response shaping. Results are serialized compactly — indented JSON measured

1.72× the bytes for identical content, so the same budget now carries about 40%

more of the data you asked for. Per-resource `self` links and link-only

relationships are stripped: no addressable content is lost, and `links.next`

survives for pagination. If a response still exceeds the budget, `included` is

dropped first, then trailing `data` items, and the result carries a `_truncated`

key saying what went missing and how to narrow the query. Note that following

`links.next` after a trim would skip the dropped items — re-request with a

smaller `limit` instead.

Build & run

cargo build --release
ASC_ISSUER_ID=... ASC_KEY_ID=... ASC_PRIVATE_KEY_PATH=/path/AuthKey_XXX.p8 \
  ./target/release/appstore-mcp

The server speaks MCP over stdio. Logs go to stderr; stdout is the

protocol channel.

Use with an MCP client

Example client config (e.g. Claude Desktop's `mcpServers`):

{
  "mcpServers": {
    "appstore": {
      "command": "/absolute/path/to/appstore-mcp/target/release/appstore-mcp",
      "env": {
        "ASC_ISSUER_ID": "00000000-0000-0000-0000-000000000000",
        "ASC_KEY_ID": "ABCD123456",
        "ASC_PRIVATE_KEY_PATH": "/absolute/path/to/AuthKey_ABCD123456.p8"
      }
    }
  }
}

Inspect with the MCP Inspector

npx @modelcontextprotocol/inspector ./target/release/appstore-mcp

Usage notes

• IDs are opaque. List/get first to resolve app, IAP, subscription, set, and

price-point IDs, then pass them to create/update tools.

• Pricing needs a price point. Use `list_iap_price_points` /

`list_subscription_price_points` to get the `id` for `set_iap_price_schedule` /

`set_subscription_price`.

• Asset uploads (`upload_*`) take a local file path and run the full reserve →

chunked upload → MD5 commit flow in one call. The file is streamed, so peak

memory is one chunk rather than the size of the asset, and a chunk that fails

is retried on its own. Screenshots/previews require an existing

`appScreenshotSet` / `appPreviewSet`; create those with the generic tools if

needed.

• Pagination. `appstore_list` returns one page by default. Pass

`max_pages` (up to 20) to follow `links.next` and merge the pages into one

result — `meta.hasMore` tells you whether anything is left.

• Analytics data. `request_analytics_report` → `list_analytics_reports` →

`list_analytics_report_instances` → `list_analytics_report_segments` gets you a

presigned segment URL; `download_analytics_segment` fetches it, gunzips it, and

returns the rows as JSON. Apple can take up to 48 hours to generate the first

report for a new request.

• Anything not listed is reachable via `appstore_request` (raw method + path +

JSON:API body) or `appstore_list` (paginated GET). Example:

`appstore_request { "method": "GET", "path": "/v1/apps/123/customerReviews" }`.

• Not covered: sales/finance report endpoints return gzipped TSV (not JSON:API)

and are out of scope for these tools.

Limitations (enforced by Apple)

• You cannot create an app via the API. The `apps` resource only allows GET and

UPDATE — `POST /v1/apps` returns `403 FORBIDDEN_ERROR`. Create the app record in

the App Store Connect website (*Apps → ➕ →

New App*); you can pre-create its bundle ID with `create_bundle_id`. All other

tools operate on an existing app.

• A deleted in-app purchase's `productId` is permanently reserved by Apple and

cannot be reused.

Development

cargo test                              # 200+ tests, no network or credentials needed
cargo clippy --all-targets -- -D warnings
cargo fmt --check

Tests come in three layers: pure unit tests for request-body builders, retry

decisions, and response shaping; `wiremock`

tests that drive the real HTTP client against a mock API (retries, timeouts,

pagination, the three-step upload protocol, segment downloads); and

`tests/tool_surface.rs`, which asserts the invariants of what a client actually

sees — unique names, real descriptions, object schemas, correct annotations, and

that `ASC_TOOLS`/`ASC_READ_ONLY` withhold exactly what they claim to.

The minimum supported Rust version is 1.88, checked by its own CI job.

Regenerate the tool reference after adding/changing tools (needs the release

binary; no credentials required):

cargo build --release && python3 scripts/gen_tools_doc.py   # rewrites docs/TOOLS.md

Live integration tests

`scripts/integration_test.py` drives the compiled server against the real API.

Read-only by default; `--write` adds a self-cleaning IAP lifecycle.

cargo build --release
# Credentials via env (ASC_ISSUER_ID/ASC_KEY_ID/ASC_PRIVATE_KEY_PATH) or local
# appstore-connect.txt + AuthKey_*.p8 in the repo root (both gitignored).
python3 scripts/integration_test.py --app           # read-only sweep
python3 scripts/integration_test.py --app  --write  # + write lifecycle

License

MIT