@ggaiteam/appstore-connect-mcp

v1.0.3

Published

13 hours ago

MCP server for the Apple App Store Connect API — exposes all 1200+ operations as MCP tools. Supports local (stdio) and remote (HTTP) deployment.

0High
0Medium
0Low

topcheer

mcp model-context-protocol apple app-store-connect appstore api claude ai llm

App Store Connect MCP

A Model Context Protocol server that exposes the entire Apple App Store Connect API (1,200+ operations) via 4 lightweight MCP tools. Query apps, manage builds, handle submissions, read analytics, manage users, and more — all from your AI assistant.

Why only 4 tools? Registering 1,216 tools would consume ~140K tokens of LLM context, making the server unusable. Instead, the LLM uses search_apis → get_tool_details → call_api to discover and execute any operation on demand — keeping context tiny while maintaining full API coverage.

Features

Complete API coverage — all 1,216 operations from the App Store Connect API v4.4
Context-friendly — only 4 MCP tools registered (not 1,216), protecting LLM context window
Tool discovery workflow — search_apis → get_tool_details → call_api
Response truncation — large API responses truncated at 25KB to fit LLM context
Two transports — stdio for local use (ggcode, Claude Desktop, Cursor), HTTP for remote deployment
JWT authentication — automatic ES256 token generation and caching
Docker ready — multi-stage Dockerfile with health checks
Auto-publish — push a git tag v1.x.x to publish to npm (OIDC, no token needed)

Quick Start

1. Get API Credentials

Go to App Store Connect → Users and Access → Keys
Click Generate API Key (or use an existing one)
Note down:
- Issuer ID — shown at the top of the Keys page
- Key ID — shown in the key list
- Private Key (.p8 file) — download it (only available once)

The key needs at least App Manager or Admin role for full functionality.

2. Install

Option A: npm (recommended)

npm install -g @ggaiteam/appstore-connect-mcp

Option B: One-line installer

curl -fsSL https://raw.githubusercontent.com/topcheer/appstore-connect-mcp/main/scripts/install.sh | bash

Option C: Docker

docker pull ghcr.io/topcheer/appstore-connect-mcp:latest

3. Configure Your MCP Client

ggcode (topcheer/ggcode) — Recommended

Add to ~/.ggcode/ggcode.yaml under mcp_servers:

mcp_servers:
  - args:
      - -y
      - '@ggaiteam/appstore-connect-mcp@latest'
    command: npx
    env:
      APP_STORE_CONNECT_ISSUER_ID: your-issuer-id-here
      APP_STORE_CONNECT_KEY_ID: your-key-id-here
      APP_STORE_CONNECT_P8_FILE: /path/to/AuthKey_XXXXXXXXXX.p8
    name: appstore-connect
    type: stdio

Restart ggcode. The 4 MCP tools (search_apis, get_tool_details, call_api, list_categories) will be available immediately.

Example session in ggcode:

> 列出我的 App Store Connect 应用列表

# ggcode will:
# 1. call_api("apps_getCollection", {arguments: {limit: 50}})
# 2. For each app, call_api("appStoreVersions_getToManyRelated", ...)
# 3. Summarize the results

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "appstore-connect": {
      "command": "npx",
      "args": ["-y", "@ggaiteam/appstore-connect-mcp"],
      "env": {
        "APP_STORE_CONNECT_ISSUER_ID": "your-issuer-id",
        "APP_STORE_CONNECT_KEY_ID": "your-key-id",
        "APP_STORE_CONNECT_P8_FILE": "/path/to/AuthKey_XXXXXXXXXX.p8"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "appstore-connect": {
      "command": "npx",
      "args": ["-y", "@ggaiteam/appstore-connect-mcp"],
      "env": {
        "APP_STORE_CONNECT_ISSUER_ID": "your-issuer-id",
        "APP_STORE_CONNECT_KEY_ID": "your-key-id",
        "APP_STORE_CONNECT_P8_FILE": "/path/to/AuthKey_XXXXXXXXXX.p8"
      }
    }
  }
}

Alternatively, inline the private key instead of a file path:
"APP_STORE_CONNECT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIGTAg...\n-----END PRIVATE KEY-----"

Restart your client.

Usage

Once connected, ask your AI assistant:

"List all my apps on App Store Connect"

"Show me the latest build for bundle ID com.example.myapp"

"Get all pending app review submissions"

"Search for subscription-related API operations"

The AI uses search_apis → get_tool_details → call_api to discover and execute operations.

4 MCP Tools

| Tool | Description | |------|-------------| | search_apis | Search 1,216 API operations by keyword, category, or HTTP method | | get_tool_details | Get full parameter schema + usage example for one operation | | call_api | Execute any API operation by name + arguments | | list_categories | List all 192 API resource categories with operation counts |

How It Works

User: "List my apps"
  ↓
AI calls: search_apis("apps")
  → finds: apps_getCollection (GET /v1/apps)
  ↓
AI calls: call_api("apps_getCollection", {arguments: {limit: 10}})
  → returns: [{name: "MyApp", bundleId: "com.example.myapp"}, ...]

Common Operations

| What | Operation | |------|----------| | List apps | call_api("apps_getCollection", {}) | | List builds | call_api("builds_getCollection", {arguments: {"filter[preReleaseVersion.build.app]": "app-id"}}) | | App versions | call_api("appStoreVersions_getCollection", {arguments: {"filter[app]": "app-id"}}) | | Beta testers | call_api("betaTesters_getCollection", {}) | | Sales reports | call_api("salesReports_getCollection", {arguments: {"filter[frequency]": "DAILY"}}) |

Remote Deployment (HTTP Mode)

Docker Compose

# 1. Create .env file
cp .env.example .env
# Edit .env with your credentials

# 2. Start
docker compose up -d

The server is available at http://localhost:3000/mcp.

Docker (manual)

docker run -d \
  --name appstore-connect-mcp \
  -p 3000:3000 \
  -e APP_STORE_CONNECT_ISSUER_ID=your-issuer-id \
  -e APP_STORE_CONNECT_KEY_ID=your-key-id \
  -e APP_STORE_CONNECT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" \
  ghcr.io/topcheer/appstore-connect-mcp:latest

Health Check

curl http://localhost:3000/health
# {"status":"ok","server":"appstore-connect-mcp","version":"1.0.0"}

Connect Remote MCP to Claude Desktop

{
  "mcpServers": {
    "appstore-connect": {
      "url": "http://your-server:3000/mcp"
    }
  }
}

CLI Usage

# Stdio mode (default — for local MCP clients)
appstore-connect-mcp

# HTTP mode (for remote deployment)
appstore-connect-mcp --transport http --port 3000 --host 0.0.0.0

# With verbose logging
appstore-connect-mcp --verbose

CLI Flags

| Flag | Default | Description | |------|---------|-------------| | --transport | stdio | Transport mode: stdio or http | | --port | 3000 | HTTP port (HTTP mode only) | | --host | 0.0.0.0 | HTTP bind host | | --issuer-id | env | App Store Connect issuer ID | | --key-id | env | API key ID | | --p8-file | env | Path to .p8 private key file | | --verbose | off | Enable verbose logging |

Environment Variables

| Variable | Description | |----------|-------------| | APP_STORE_CONNECT_ISSUER_ID | Issuer ID from App Store Connect | | APP_STORE_CONNECT_KEY_ID | Key ID | | APP_STORE_CONNECT_PRIVATE_KEY | PEM private key content (inline) | | APP_STORE_CONNECT_P8_FILE | Path to .p8 file (alternative to above) | | MCP_TRANSPORT | stdio or http | | MCP_PORT | HTTP port | | MCP_HOST | HTTP host | | MCP_VERBOSE | 1 to enable verbose logging |

Architecture

┌──────────────────┐     ┌──────────────────┐
│  MCP Client      │     │  MCP Server      │
│  (Claude, etc.)  │◄───►│                  │
└──────────────────┘     │  ┌────────────┐  │     ┌─────────────────┐
                         │  │ Tool       │  │     │ App Store       │
   stdio or HTTP/SSE     │  │ Registry   │──┼────►│ Connect API     │
                         │  │ (1,216     │  │     │ api.appstore    │
                         │  │  tools)    │  │     │ connect.apple   │
                         │  └────────────┘  │     │ .com            │
                         │       │          │     └─────────────────┘
                         │  ┌────▼─────┐    │            ▲
                         │  │ JWT Auth │    │            │
                         │  │ (ES256)  │────┼────────────┘
                         │  └──────────┘    │
                         └──────────────────┘

Tool data is generated from Apple's OpenAPI spec (scripts/generate-tools.py)
Runtime loads tools.json (1,216 ops) but only registers 4 MCP tools
JWT tokens are cached and auto-refreshed (20-minute TTL)
Responses are truncated at 25KB to fit LLM context windows

Regenerating Tools

When Apple updates their API:

# Download the latest OpenAPI spec
# https://developer.apple.com/app-store-connect/

# Generate updated tools.json
python3 scripts/generate-tools.py openapi.oas.json src/tools.json

# Rebuild
npm run build

Development

# Clone
git clone https://github.com/topcheer/appstore-connect-mcp.git
cd appstore-connect-mcp

# Install
npm install

# Generate tools from OpenAPI spec
npm run generate

# Build
npm run build

# Run locally
APP_STORE_CONNECT_ISSUER_ID=... \
APP_STORE_CONNECT_KEY_ID=... \
APP_STORE_CONNECT_P8_FILE=... \
npm start

Project Structure

├── scripts/
│   ├── generate-tools.py     # OpenAPI → tools.json generator
│   └── install.sh            # One-line installer
├── src/
│   ├── index.ts              # Entry point + CLI
│   ├── server.ts             # MCP server (4 tools: search/details/call/list)
│   ├── transport.ts          # stdio + HTTP transports
│   ├── auth.ts               # JWT (ES256) token generation
│   ├── client.ts             # App Store Connect API client
│   ├── tools.ts              # Tool schema builder + executor
│   ├── types.ts              # TypeScript type definitions
│   └── tools.json            # Generated tool definitions (1,216 ops)
├── Dockerfile                # Multi-stage Docker build
├── docker-compose.yml        # Remote deployment config
├── .github/workflows/
│   ├── ci.yml                # Lint + build + test
│   ├── npm-publish.yml       # Auto-publish to npm on release
│   └── docker.yml            # Build + push Docker image
└── package.json

npm Publishing

Publishing is fully automated via GitHub Actions with OIDC trusted publishing — no NPM_TOKEN needed.

Release a new version

git tag v1.0.3
git push origin v1.0.3

That's it. The workflow will:

Extract version from the tag
Check if version already exists on npm (skip if so)
Build the package
Publish to npm with --provenance=false --access public
Auto-create a GitHub Release

First-time setup (already done)

Package must exist on npm (first publish is manual: npm publish --access public)
Configure trusted publishing on npm: link the package to topcheer/appstore-connect-mcp
No NPM_TOKEN secret needed — OIDC handles authentication

API Coverage

This server covers all 1,216 operations across the App Store Connect API:

| Method | Count | |--------|-------| | GET | 768 | | POST | 168 | | PATCH | 153 | | DELETE | 127 |

Including: Apps, Builds, App Store Versions, Beta Testing, Subscriptions, In-App Purchases, User Management, Sales Reports, Analytics, App Clips, Game Center, and more (192 categories total).

Security

Private keys are read from environment variables or files — never logged
JWT tokens are short-lived (20 minutes max) and cached in memory only
No data is stored or persisted between requests
For remote deployment, use HTTPS/TLS termination at your reverse proxy

License

MIT — see LICENSE

Acknowledgments

Apple App Store Connect API — API and OpenAPI specification
Model Context Protocol — Protocol specification