app-store-connect-mcp

# Heimdall — App Store Connect MCP

<!-- Absolute URL on purpose: npm does not rewrite relative image paths. -->
<img src="https://raw.githubusercontent.com/erayendes/app-store-connect-mcp/main/assets/brand/heimdall-social-card.png" alt="Heimdall — App Store Connect MCP" width="720">

[![npm version](https://img.shields.io/npm/v/%40erayendes%2Fasc-mcp.svg)](https://www.npmjs.com/package/@erayendes/asc-mcp)
[![npm downloads](https://img.shields.io/npm/dm/%40erayendes%2Fasc-mcp.svg)](https://www.npmjs.com/package/@erayendes/asc-mcp)
[![CI](https://github.com/erayendes/app-store-connect-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/erayendes/app-store-connect-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Yerli üretim](https://img.shields.io/badge/YERL%C4%B0%20%C3%9CRET%C4%B0M-red?style=flat&label=%F0%9F%A4%9D&color=red&link=https%3A%2F%2Fmilowda.com)](https://milowda.com)

<!-- Absolute URL on purpose: npm does not rewrite relative image paths. -->
<img src="https://raw.githubusercontent.com/erayendes/app-store-connect-mcp/main/assets/demo.gif" alt="Asking an agent what a subscription costs worldwide; Heimdall answers in one tool call" width="720">

<sub>A real agent session over MCP, sped up. The App Store Connect account is a stand-in so the recording can be public — regenerate with `vhs assets/demo/demo.tape`.</sub>

🇬🇧 [English](#english) · 🇹🇷 [Türkçe](#türkçe)

## English

**Heimdall.** One tool for your entire App Store Connect account.

An MCP server for the **App Store Connect API** and the **App Store Server API (StoreKit 2)**, with every tool generated from Apple's own OpenAPI specification. **13 profiles, 32 sub-profiles, 890 tools.**

Apps and metadata, versions and phased releases, TestFlight, subscriptions and in-app purchases, pricing, reviews, Game Center, Xcode Cloud, provisioning, webhooks, and sales and finance reports.

### Ask and it answers. Tell it and it's done.
> - *"Summarise this week's 1-star reviews and draft replies."*
> - *"Which builds are stuck in review?"*
> - *"Raise this subscription's price in every territory."*

### What the one call saves

| The question | Through the raw tools | Heimdall |
|:--|:--|:--|
| *"What does this subscription cost in every country?"* | one measured agent session: 1.02M tokens, $3 | ~1.3k tokens, 2.1s |
| *"What screenshots are on the listing?"* | 53 HTTP calls, 264 KB | 4 calls, ~1 KB |
| *"Change this subscription's price."* | 4 reads, then a choice among 842 price points | one call |

The first row is a real session, not a projection: the agent walked the chain, could not fit the answer, wrote it to a CSV and hand-built a country-name dictionary in Python to finish. The other two are call counts against a live account.

### Quick start

```bash
npx -y @erayendes/asc-mcp setup
```

<!-- Absolute URL on purpose: npm does not rewrite relative image paths. -->
<img src="https://raw.githubusercontent.com/erayendes/app-store-connect-mcp/main/assets/setup.gif" alt="The setup wizard: key, issuer ID, credential check, profile and sub-profile selection, key stored in the Keychain" width="720">

<sub>One pass, and safe throughout: the access details it needs, then a live credential check. Then your choices — the profiles and sub-profiles you want, and the key ends up in the Keychain, not in a config file.</sub>

The setup wizard asks for your API key once, stores it safely, and registers the profiles you choose with **every MCP client on your machine** — Claude, Codex, Antigravity, Cursor, Windsurf, VS Code. None of them share a config file, so **this is the step you would otherwise repeat once per client, in a different format each time.** Time thrown away.
Full walkthrough in the [Guide](docs/GUIDE.md).

**Xcode 27** is not on that list because Xcode has no config file to write — it installs plug-ins from a Git URL. After `setup`, open Xcode → Settings → Intelligence → Plug-ins → Add Plug-in → **Add from URL**, paste `https://github.com/erayendes/app-store-connect-mcp`, and tick **Heimdall | ASC Skill** plus the areas you need. Then pick an **agent** in the conversation's model menu — Claude Agent, Codex or Gemini — rather than a built-in model: plug-ins reach the agents, not Xcode's own chat. The agent launches the same servers, and they read the key `setup` stored.
> **Is an AI agent installing Heimdall for you?**
> See [AGENTS.md](AGENTS.md) for the handoff protocol: the agent adds the profiles with `register`, you run `setup` yourself for the key — your private key is for your eyes only, and the agent never sees it.

### What sets Heimdall apart

Most App Store Connect MCP servers offer a hand-picked slice of the API. That works right up until you need the one endpoint none of them covered. Heimdall does the opposite: it gives you all of the tools and lets you choose which ones you want — and change your mind whenever you like.

| | |
| :--- | :--- |
| **Complete** | Apple's OpenAPI spec v4.4.1, all 966 paths, 982 operations — 281 id-only duplicates already collapsed, and the 123 Apple has deprecated stay unloaded unless you ask for them, which leaves the 859 reachable operations plus 31 hand-written tools. `npm run spec:update` brings Apple's changes in as a reviewable diff. |
| **Narrowable** | 13 purpose-built profiles, each narrowing further — `monetization:subscription-pricing` is 27 tools instead of 207. The whole surface would cost over 100k tokens of tool definitions; one profile costs a fraction of that. |
| **StoreKit 2** | The App Store Server API too — customer transactions, entitlements, refunds. **Rare among ASC MCP servers.** |
| **No second API key** | Review triage, daily briefings and draft replies return the review data — your own model writes the text. |
| **Safe** | Confirm-before-write, `--read-only`, destructive-action annotations, host-pinned requests, no telemetry. |
| **Private** | The `.p8` lives in the macOS Keychain, never in a plain-text config. |

#### Profiles
<!-- Absolute URL on purpose: npm does not rewrite relative image paths. -->
<img src="https://raw.githubusercontent.com/erayendes/app-store-connect-mcp/main/assets/picker.gif" alt="The profile picker: checking monetization unfolds its sub-profiles, each with its tool count and token estimate" width="720">

Register only the profiles your project uses. What each one covers is in the [profile table](docs/GUIDE.md#register-profiles); adding and removing them later is [here](docs/GUIDE.md#adding-and-removing-later).

Not sure which? [Starter packs](docs/GUIDE.md#starter-packs) answers it by role — a release manager installs `distribution` + `app-info`, an ASO team `marketing` + `analytics` — and [examples/](examples/README.md) works each one through, including the part that usually goes wrong.

There is nothing to memorise — ask *"is there a tool for in-app events?"* and `asc__search_tools` searches everything, including what isn't loaded, and tells you which profile it lives in.

#### Risky writes ask first

Changing a price, handing out Admin or deleting something asks for confirmation before it runs, showing what would change, so a misread instruction cannot execute unchecked. This is the default for the four risk levels that are hard to undo — revenue, destructive, infrastructure, access — and everything else runs on your client's own tool approval. `--confirm` asks before every write instead; `--no-confirm` asks before none; `--read-only` drops mutating tools entirely. See [Security](.github/SECURITY.md).

#### Least privilege, and a way to check it

Apple never returns a key's role from any endpoint, so **App Manager** — not Admin — is the right default for day-to-day release work; Admin only earns its place for user management and for the one-time first request of a new analytics report type, which has no path in the App Store Connect UI at all. Contracts, tax and banking sit behind the Account Holder alone, reachable by no API key regardless of role. Call `asc__status` with `check_capabilities: true` to see what a key actually has rather than guessing from a 403 mid-task. Full breakdown in the [Guide](docs/GUIDE.md#least-privilege-in-practice).

#### Local by design, not by default

MCP guidance recommends remote HTTP servers: one URL, no install, updates you control. Heimdall runs locally over stdio instead, and that is a deliberate trade. Running locally, the key never leaves your machine: Heimdall reads it from the Keychain, signs a short-lived token, and talks to Apple directly. Nothing sits in between.

The cost is real and worth naming: you need Node installed, and you update by version rather than by us pushing one. That is the price of the key staying yours.

#### Works alongside Fastlane

Heimdall is not a Fastlane alternative — it is the interactive half. Keep [Fastlane](https://fastlane.tools/) for repeatable, scripted CI work (code signing, build upload, metadata pushes). Fastlane for the pipeline, Heimdall for exploration and one-off changes.

### Documentation

- [Guide](docs/GUIDE.md) — API key, install, setup wizard, profiles, configuration, examples
- [Examples](examples/README.md) — starter packs by role, seven worked scenarios, and a GitHub Actions workflow
- [Security](.github/SECURITY.md) — credential handling, safety modes, pre-install audit, vulnerability reporting
- [Support](.github/SUPPORT.md) — getting help, troubleshooting
- [Changelog](docs/CHANGELOG.md) — release history
- [Contributing](.github/CONTRIBUTING.md) — how to contribute, local dev setup
- [Code of Conduct](.github/CODE_OF_CONDUCT.md)
- [Governance](.github/GOVERNANCE.md) — who maintains this and why

### Support the project

Heimdall is free and open. If it saves you time, you can [become a member or buy me a coffee](https://buymeacoffee.com/erayendes) ☕.

### About the name

**Heimdall** is the guardian of Asgard in Norse mythology and one of Odin's sons. He keeps watch over **Bifrö