Unofficial App Store Connect MCP Server

An MCP server that gives AI assistants structured access to App Store Connect data. Built for ASO (App Store Optimization) analysis, download tracking, and performance monitoring.

The server returns agent-friendly JSON with natural-language summaries, pre-computed aggregations, and conversion rates — so an AI agent can interpret App Store data without needing domain-specific knowledge of Apple's raw report formats.

Table of Contents

• Quick Start

• Tools

• How Analytics Reports Work

• Response Format

• Local Testing

• Development

• Contributing

• License

Related MCP server: appstore-intel-mcp

Quick Start

Prerequisites

You need an App Store Connect API key. Create one at App Store Connect > Users and Access > Integrations > App Store Connect API.

Install

git clone https://github.com/Fourni-j/appstore-connect-MCP.git
cd appstore-connect-MCP
npm install
npm run build

Configure your MCP client

Add to your MCP client config (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "appstore-connect": {
      "command": "node",
      "args": ["/path/to/appstore-connect-MCP/dist/index.js"],
      "env": {
        "ASC_KEY_ID": "your-key-id",
        "ASC_ISSUER_ID": "your-issuer-id",
        "ASC_PRIVATE_KEY_PATH": "/path/to/AuthKey_XXXX.p8",
        "ASC_VENDOR_NUMBER": "your-vendor-number"
      }
    }
  }
}

Environment Variables

First command

Ask your AI assistant:

"List my apps on App Store Connect"

Tools

list_apps

List all apps in the account. Returns each app's id, name, bundleId, and sku. The returned id is used as appId in all other tools.

Parameters: limit (optional, default 50, max 200)

get_app_metadata

Get localized metadata: title, subtitle, keywords, description, and promotional text for all locales. Useful for ASO review.

Parameters: appId (required)

get_analytics_report

Get analytics data for an app across five categories:

Returns aggregated data per period by default, with totals and breakdowns by source/device/territory. For engagement, COMMERCE download data is automatically merged, including the conversion rate (Total Downloads / Unique Impressions) matching App Store Connect's definition exactly.

Set raw: true for granular per-territory/device/OS rows.

Always specify granularity (DAILY or MONTHLY). Without it, Apple mixes monthly and daily instances. MONTHLY covers completed months only; DAILY covers recent days. For a full picture, make two calls.

Parameters: appId (required), category (required), granularity (optional but recommended), startDate (optional), endDate (optional), raw (optional), limit (optional)

get_sales_report

Download and parse sales/installs reports as structured JSON. Apple's raw TSV column names are mapped to readable camelCase keys. Each row includes a productTypeLabel with a human-readable description.

Parameters: reportType (required), reportSubType (required), frequency (required), vendorNumber (optional — falls back to ASC_VENDOR_NUMBER), reportDate (optional)

get_app_store_versions

List app versions with their App Store state (READY_FOR_SALE, IN_REVIEW, etc.), creation date, and platform. Useful for correlating releases with metric changes.

Parameters: appId (required), limit (optional, default 10, max 50)

get_downloads_summary

Get first-time download counts aggregated by period. Automatically uses daily granularity for ranges under 32 days, monthly otherwise. Only counts new installs (excludes updates, re-downloads, IAPs, and subscriptions).

Parameters: appId (required), startDate (optional), endDate (optional)

get_customer_reviews

Get customer reviews and ratings for an app. Returns individual written reviews with aggregated statistics (average rating, star distribution), plus the official App Store rating from the iTunes Lookup API.

The App Store rating includes all ratings (silent star taps + written reviews) and varies by country — set storeCountry to get the rating for a specific market.

Parameters: appId (required), rating (optional, 1-5), territory (optional, 3-letter code like USA, FRA), sort (optional, default -createdDate), startDate (optional), endDate (optional), storeCountry (optional, 2-letter ISO code, default US), limit (optional, default 500, max 1000)

How Analytics Reports Work

Analytics reports use Apple's asynchronous reporting flow. This is different from the other tools — it doesn't return data from a single API call.

The flow:

1. Report request — The server creates an ONGOING analytics report request for your app

2. Report generation — Apple processes the request and produces report instances (one per time period)

3. Segment download — Each instance contains segments (gzipped TSV files) that the server downloads and parses

First-time setup: The very first call for a given app creates the report request and returns a "pending" status. Apple needs time (typically a few hours, sometimes up to 24h) to generate the initial reports. Subsequent calls return data immediately.

Why it can be slow: Even after initial setup, fetching analytics involves multiple chained API calls. For large date ranges with many instances, this can take 10-30 seconds.

See Apple's Analytics Reports documentation for the full API reference.

Response Format

All tools return JSON with an agent-friendly structure:

{
  "summary": "APP_STORE_ENGAGEMENT analytics from 2026-02-01 to 2026-02-28: 28 periods...",
  "status": "ready",
  "granularity": "daily",
  "dateRange": { "from": "2026-02-01", "to": "2026-02-28" },
  "totals": { "Impression": 50000, "Page view": 8000, "Tap": 3200 },
  "uniqueTotals": { "Impression": 40000, "Page view": 7000, "Tap": 2800 },
  "conversionRates": {
    "tapRate (Unique Taps / Unique Impressions)": "7.00%",
    "pageViewRate (Unique Page Views / Unique Impressions)": "17.50%",
    "conversionRate (Total Downloads / Unique Impressions)": "4.50%"
  },
  "downloads": {
    "totalDownloads": 1800,
    "firstTimeDownloads": 1500,
    "redownloads": 300,
    "updates": 500
  },
  "periods": [
    {
      "date": "2026-02-01",
      "counts": { "Impression": 1800, "Page view": 290, "Tap": 115 },
      "uniqueCounts": { "Impression": 1400, "Page view": 250, "Tap": 100 },
      "conversionRates": { "...": "..." },
      "bySource": { "App Store Browse": 900, "App Store Search": 700 },
      "byDevice": { "iPhone": 1400, "iPad": 400 },
      "downloads": { "totalDownloads": 60, "firstTimeDownloads": 50, "redownloads": 10 }
    }
  ]
}

{
  "summary": "DAILY SALES/SUMMARY report for 2026-02-15: 12 rows.",
  "totalRows": 12,
  "truncated": false,
  "data": [
    {
      "title": "My App",
      "sku": "com.example.myapp",
      "units": "5",
      "customerPrice": "0",
      "productType": "1",
      "productTypeLabel": "Free or Paid App (Universal)",
      "countryCode": "US",
      "device": "iPhone"
    }
  ]
}

{
  "summary": "App Store rating (US): 4.58 from 178 ratings. 42 written reviews (avg 3.26). Distribution: 5★=16, 4★=10, 3★=8, 2★=3, 1★=5.",
  "appId": "123",
  "storeRating": {
    "averageRating": 4.58,
    "ratingCount": 178,
    "currentVersionAverageRating": 4.58,
    "currentVersionRatingCount": 178
  },
  "totalReviews": 42,
  "averageRating": 3.26,
  "ratingDistribution": { "1": 5, "2": 3, "3": 8, "4": 10, "5": 16 },
  "truncated": false,
  "reviews": [
    {
      "id": "review-id",
      "rating": 5,
      "title": "Great app!",
      "body": "Love the barcode scanning feature.",
      "reviewerNickname": "user123",
      "territory": "USA",
      "createdDate": "2026-03-01T00:00:00Z"
    }
  ]
}

{
  "error": "ASC_VENDOR_NUMBER environment variable is not set. Find your vendor number in App Store Connect > Payments and Financial Reports."
}

Error responses also set isError: true on the MCP result object.

Local Testing

Run tool handlers directly against the real App Store Connect API:

# Set environment variables first
export ASC_KEY_ID="your-key-id"
export ASC_ISSUER_ID="your-issuer-id"
export ASC_PRIVATE_KEY_PATH="/path/to/AuthKey_XXXX.p8"
export ASC_VENDOR_NUMBER="your-vendor-number"

# Run all tools
npx tsx scripts/test-tools.ts

# Run a specific tool
npx tsx scripts/test-tools.ts list-apps
npx tsx scripts/test-tools.ts get-analytics-report
npx tsx scripts/test-tools.ts get-customer-reviews

Development

npm run build        # Compile TypeScript
npm test             # Run tests (94 tests)
npm run test:watch   # Watch mode
npm start            # Start the MCP server

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

License

MIT License — see LICENSE for details.