asc-mcp

# asc-mcp An unofficial MCP server for the App Store Connect API — automate releases, App Review, metadata, screenshots, TestFlight, product page experiments, diagnostics, reports, reviews, and ASO analysis. ## Capabilities - Retrieve a list of apps registered on App Store Connect - Obtain customer reviews (sortable by order, country, and star rating) and post developer responses - Get a list of TestFlight builds (with processing status and expiration date) - Retrieve App Store version lists (with review status and release type) - Obtain sales summary reports (daily, weekly, monthly, yearly) - Check keyword search rankings on the App Store (no authentication required) - Retrieve Analytics Reports (ASO analysis data such as impressions, product page views, and download sources) - Create, localize, and build App Store versions, update review information, and submit for review - Create screenshot sets, split and upload local images, list and delete - Manage manual, automatic, and scheduled releases, phased releases, distribution countries, and app prices - Manage TestFlight groups, testers, builds, What to Test, and external test reviews - Create and update custom product pages and Product Page Optimization - Obtain crash and hang diagnostic logs, performance metrics such as launch time ## Quick Start ### 1. Prepare App Store Connect API Key Create an API key on [App Store Connect](https://appstoreconnect.apple.com/) under **Users and Access** > **Integrations** > **App Store Connect API** > **Team Keys**, and download the `.p8` file. The role should be **Admin** if you need to use sales reports (`asc_get_sales_report`), otherwise **App Manager** is sufficient. Note that the private key can only be downloaded once. ### 2. Build ```bash git clone https://github.com/Hiru-ge/asc-mcp.git cd asc-mcp npm install npm run build ``` ### 3. Register with MCP Client For Claude Code: ```bash claude mcp add --scope user app-store-connect \ -e ASC_KEY_ID=xxx \ -e ASC_ISSUER_ID=xxx \ -e ASC_PRIVATE_KEY_PATH=/path/to/AuthKey_xxx.p8 \ -- node /path/to/asc-mcp/dist/index.js ``` Replace `/path/to/asc-mcp` with the absolute path of the cloned directory. If using sales reports, add `-e ASC_VENDOR_NUMBER=xxxxx` (see [Vendor Number for Sales Reports](#vendor-number-for-sales-reports)). ### 4. Try it out Ask the agent in a new session: > Show me the latest 5 customer reviews. > What is the ranking of my app when searching for "cafe khai拓"? ## App Store Connect API Key Creation 1. Log in to [App Store Connect](https://appstoreconnect.apple.com/). 2. Go to **Users and Access** > **Integrations** > **App Store Connect API** > **Team Keys**. 3. Create a new API key and select the role: - **App Manager**: Covers app information, review retrieval and response, builds, versions, and Analytics Reports. Insufficient permissions for sales reports (returns HTTP 403). - **Admin** or **Sales**: Required for sales reports (`asc_get_sales_report`). Sales role specializes in Sales and Trends access but may lack permissions for other tools. ### Issuer ID / Key ID Location - **Issuer ID**: Displayed at the top of the **Integrations** > **App Store Connect API** page (e.g., `57246542-96fe-1a63-e053-0824d011072a`). A shared value for the entire team. - **Key ID**: A 10-character identifier displayed in the list of created keys (e.g., `2X9R4HXF34`). Included in the `.p8` file name as `AuthKey_<Key ID>.p8`. ### Vendor Number (for Sales Reports) Displayed on the **Payments and Financial Reports** page of App Store Connect, a vendor number (numeric only) for each contract. ## Environment Variables | Variable Name | Required | Description | |---|---|---| | `ASC_KEY_ID` | Required | API key's Key ID | | `ASC_ISSUER_ID` | Required | Issuer ID | | `ASC_PRIVATE_KEY_PATH` | Required | Absolute path to the downloaded `.p8` file | | `ASC_VENDOR_NUMBER` | Optional | Vendor number for retrieving sales reports (`asc_get_sales_report`) | If any required environment variable is missing, the server will start but an error message will be returned when calling each tool. ## Tool List | Tool Name | Purpose | |---|---| | `asc_list_apps` | Retrieve a list of apps registered on App Store Connect (id, name, bundleId, sku, primaryLocale) | | `asc_list_customer_reviews` | Obtain customer reviews for a specified app, filterable by order, country, and star rating | | `asc_reply_to_review` | Post a developer response to a customer review | | `asc_list_builds` | Retrieve a list of uploaded builds for a specified app (in descending order of upload time) | | `asc_list_app_store_versions` | Retrieve App Store version lists for a specified app (review status, release type, etc.) | | `asc_get_sales_report` | Obtain a sales summary report (SALES/SUMMARY/version 1.0) as TSV, parse and return. Requires `ASC_VENDOR_NUMBER` | | `asc_search_ranking` | Check keyword search rankings on the App Store using the public iTunes Search API (no App Store Connect authentication required) | | `asc_request_analytics_reports` | Ensure an ONGOING request for Analytics Reports | | `asc_list_analytics_reports` | Retrieve a list of available reports using the `requestId` obtained from `asc_request_analytics_reports` | | `asc_get_analytics_report_data` | Obtain and parse report instance data (CSV/TSV) using the `reportId` obtained from `asc_list_analytics_reports` | | `asc_create_app_store_version` | Create a new App Store version | | `asc_create_version_localization` | Create localization for a version | | `asc_list_version_localizations` | Retrieve localization details (description, keywords, what's new, etc.) for a version | | `asc_update_version_localization` | Partially update version localization | | `asc_list_app_info_localizations` | Retrieve localization details (app name, subtitle, privacy policy URL, etc.) for an app | | `asc_update_app_info_localization` | Partially update app information localization | | `asc_set_version_build` | Associate a build with an App Store version | | `asc_get_review_details` | Retrieve review details (contact, demo account, review notes) | | `asc_create_review_details` | Create review details | | `asc_update_review_details` | Partially update review details | | `asc_submit_app_store_version` | Create a review submission, add a version, and submit for review | | `asc_submit_product_page_review_item` | Submit a Product Page Optimization experiment or custom page for review | | `asc_create_screenshot_set` | Create a screenshot set for a standard page, experiment, or custom page | | `asc_list_screenshot_sets` | Retrieve screenshot sets for a localization | | `asc_list_screenshots` | Retrieve screenshots and their processing status within a set | | `asc_upload_screenshot` | Upload a local image with reservation, split upload, and commit | | `asc_delete_screenshot_resource` | Delete a screenshot or set | | `asc_update_app_store_version` | Update release type, scheduled release date, copyright, etc. | | `asc_enable_phased_release` | Enable a 7-day phased release | | `asc_update_phased_release` | Start, pause, resume, or complete a phased release | | `asc_release_app_store_version` | Publish a manually released version awaiting approval | | `asc_list_app_price_points` | Retrieve price points and revenue amounts for each distribution country | | `asc_get_app_price_schedule` | Retrieve current and scheduled prices, price point IDs | | `asc_set_app_price` | Change the base country's price immediately or schedule a change | | `asc_get_app_availability` | Retrieve distribution status, release date, and pre-order settings by country | | `asc_list_territory_availabilities` | Retrieve pagination settings for all distribution countries | | `asc_update_territory_availability` | Update distribution availability and release date for a single country | | `asc_list_beta_groups` | Retrieve TestFlight groups | | `asc_create_beta_group` | Create a TestFlight group | | `asc_list_beta_testers` | Retrieve TestFlight testers | | `asc_create_beta_tester` | Create and invite a TestFlight tester | | `asc_add_to_beta_group` | Add a tester or build to a group | | `asc_list_beta_build_localizations` | Retrieve What to Test for each localization | | `asc_set_beta_build_localization` | Create or update What to Test for each localization | | `asc_get_build_beta_details` | Retrieve internal and external test status for a TestFlight build | | `asc_update_build_beta_details` | Update automatic invitation for external testing | | `asc_submit_beta_app_review` | Submit a build for external TestFlight review | | `asc_list_product_page_experiments` | Retrieve Product Page Optimization experiments | | `asc_create_product_page_experiment` | Create a Product Page Optimization experiment | | `asc_update_product_page_experiment` | Update experiment allocation, status, and name | | `asc_create_experiment_treatment` | Create an experiment treatment | | `asc_list_experiment_treatments` | Retrieve experiment treatments | | `asc_create_experiment_treatment_localization` | Create localization for a treatment | | `asc_list_custom_product_pages` | Retrieve custom product pages | | `asc_create_custom_product_page` | Create a custom product page | | `asc_update_custom_product_page` | Update a custom product page's name and display status | | `asc_create_custom_product_page_version` | Create an editable version of a custom product page | | `asc_list_custom_product_page_versions` | Retrieve versions of a custom product page | | `asc_update_custom_product_page_version` | Update a custom product page's deep link | | `asc_create_custom_product_page_localization` | Create localization for a custom page | | `asc_get_performance_metrics` | Retrieve power and performance metrics for an app or build | | `asc_list_diagnostic_signatures` | Retrieve diagnostic signatures (crashes, hangs, etc.) for a build | | `asc_get_diagnostic_logs` | Retrieve anonymized logs and call stacks for diagnostic signatures | Each list tool supports pagination with `limit` (default 20, max 200) and `nextUrl`. ### Basic Flow for Review Submission 1. Create a version with `asc_create_app_store_version`. 2. Add updates with `asc_create_version_localization` or `asc_update_version_localization`. 3. Update images with `asc_create_screenshot_set` and `asc_upload_screenshot` if necessary. 4. Associate a processed build with `asc_set_version_build`. 5. Prepare review notes with `asc_create_review_details` or `asc_update_review_details`. 6. Submit for review with `asc_submit_app_store_version`. Pass the absolute path of a local file readable by the MCP server process as `filePath` for `asc_upload_screenshot`. For Product Page Optimization sets, specify `experimentTreatment` for `localizationType`, and for custom product pages, specify `customProductPage`. ### How to Use ASO Analysis Tools - `asc_search_ranking` can be used alone without authentication. It works even if `ASC_KEY_ID` etc. are not set. - Analytics Reports follow a 3-step flow: **`asc_request_analytics_reports` → `asc_list_analytics_reports` → `asc_get_analytics_report_data`**. - Creating an ONGOING request with `asc_request_analytics_reports` may take up to 48 hours to generate a report. Calling `asc_list_analytics_reports` before generation will return an empty result. - Reusing existing ONGOING requests allows you to skip recreating them; just keep the `requestId`. ## Security Notes - Review text returned by `asc_list_customer_reviews` is unverified text that third-party users can freely write. This text may contain instructions (prompt injection) that could be executed by an LLM reading the text. - Since `asc_reply_to_review` for public responses and the server coexist, malicious review text could include instructions for the agent. Ensure that `asc_reply_to_review` is not included in auto-approve settings and that execution content is confirmed by a human before approval. - Tools for review submission, publication, pricing, distribution countries, and screenshot deletion modify actual App Store Connect data. Do not add these to auto-approve settings; confirm the target app, version, country, and price before execution. ## Implementation Notes - JWT is signed with ES256 using `jose`'s `importPKCS8` and `SignJWT`. The expiration time is set to 19 minutes, with a 2-minute buffer before regeneration. - List tool responses are flattened arrays in JSON:API's `attributes` to reduce token consumption. - Sales reports are requested with `Accept: application/a-gzip`, expanded to TSV with `node:zlib`'s `gunzipSync`, and parsed. For large reports, only the first 50 rows and total rows are returned. - `asc_search_ranking` uses a plain `fetch` to hit `https://itunes.apple.com/search` (no JWT). The iTunes Search API has a rate limit of approximately 20 requests/minute; exceeding this may return HTTP 403. - Analytics Reports' segment data (signed URLs) are downloaded with a plain `fetch` and expanded with `gunzipSync`. Segments are in CSV or TSV; delimiter detection is based on the presence of tabs in the first line. Multiple segments are combined, and only the first 50 rows and total rows are returned. ## Disclaimer This tool is an unofficial open-source project unrelated to Apple Inc. Apple, App Store Connect, and iTunes are trademarks of their respective companies. ## License [MIT](./LICENSE)