asc-mcp

MCP server for the Apple App Store Connect API — Xcode Cloud CI, app management, customer reviews, and sales reports.

Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.

---

How it works

sequenceDiagram
    participant C as MCP Client<br/>(Claude Code, Cursor…)
    participant S as asc-mcp
    participant A as App Store Connect API

    C->>S: initialize (stdio)
    S-->>C: serverInfo + capabilities

    C->>S: tools/list
    S-->>C: 11 tools with JSON Schema

    C->>S: tools/call list_products
    S->>S: generate JWT (ES256, cached 15m)
    S->>A: GET /v1/ciProducts
    A-->>S: JSON:API response
    S-->>C: pretty JSON result

---

Architecture

graph TD
    Client["MCP Client<br/>(Claude Code / Cursor / Windsurf)"]
    Server["AscMcpServer<br/>tools.rs — rmcp #[tool_router]"]
    HttpClient["AscClient<br/>client.rs + client_endpoints.rs"]
    Auth["Credentials<br/>auth.rs — ES256 JWT cache"]
    Models["models/<br/>JSON:API types"]
    API["App Store Connect API v1<br/>api.appstoreconnect.apple.com"]

    Client -->|stdio MCP protocol| Server
    Server --> HttpClient
    HttpClient --> Auth
    HttpClient --> Models
    HttpClient -->|HTTPS| API

---

Features

• Xcode Cloud CI/CD — list products, workflows, build runs, actions; trigger builds
• App management — list and inspect apps
• Customer reviews — fetch with full auto-pagination
• Sales reports — download and parse gzip-compressed TSV reports
• JWT auth — ES256 tokens generated and cached for 15 minutes
• Rate-limit handling — automatic retry with Retry-After respect (3 attempts)
• Zero config — three env vars and you're running

---

Installation

cargo install asc-mcp

Or build from source:

git clone https://github.com/menot-you/apple-store-connect
cd apple-store-connect
cargo install --path .

---

Configuration

Generate an API key at App Store Connect → Users and Access → Integrations → App Store Connect API.

Variable	Description
ASC_KEY_ID	Key ID shown in App Store Connect
ASC_ISSUER_ID	Issuer ID shown at the top of the API keys page
ASC_PRIVATE_KEY_PATH	Path to the .p8 file downloaded from App Store Connect

---

Usage

Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "asc-mcp": {
      "command": "asc-mcp",
      "env": {
        "ASC_KEY_ID": "YOUR_KEY_ID",
        "ASC_ISSUER_ID": "YOUR_ISSUER_ID",
        "ASC_PRIVATE_KEY_PATH": "/path/to/AuthKey_XXXX.p8"
      }
    }
  }
}

Cursor / Windsurf / other MCP clients

Same structure — add to your client's MCP server config file.

---

Available Tools

Xcode Cloud

graph LR
    list_products --> get_product
    get_product --> list_workflows
    list_workflows --> list_build_runs
    list_workflows --> start_build
    list_build_runs --> get_build_run
    get_build_run --> list_build_actions

Tool	Parameters	Description
list_products	—	List all Xcode Cloud CI products
get_product	product_id	Get details of a specific CI product
list_workflows	product_id	List workflows for a CI product
list_build_runs	workflow_id	List build runs for a workflow
get_build_run	build_run_id	Get details of a specific build run
start_build	workflow_id, git_reference_id	Trigger a new build
list_build_actions	build_run_id	List actions inside a build run

Apps & Reviews

Tool	Parameters	Description
list_apps	—	List all apps in App Store Connect
get_app	app_id	Get details of a specific app
list_customer_reviews	app_id	List customer reviews for an app

Sales Reports

Tool	Parameters	Description
get_sales_report	vendor_number, report_type, report_sub_type, frequency, report_date	Download and parse a sales report

report_type values: SALES, SUBSCRIPTION, SUBSCRIPTION_EVENT frequency values: DAILY, WEEKLY, MONTHLY, YEARLY report_date format: YYYY-MM-DD

---

Token lifecycle

stateDiagram-v2
    [*] --> NoToken
    NoToken --> Generating: first request
    Generating --> Cached: JWT signed (ES256)
    Cached --> Cached: elapsed < 15m → reuse
    Cached --> Generating: elapsed ≥ 15m → refresh

Apple allows 20-minute tokens; this server uses 15-minute TTL for a 5-minute clock-skew buffer.

---

Development

cargo test          # 47 tests, no credentials needed
cargo clippy -- -D warnings
cargo fmt --check
cargo doc --no-deps

Tests use wiremock for real HTTP-level mocking — no Apple account required.

See CONTRIBUTING.md for the full guide and ARCHITECTURE.md for the design walkthrough.

---

License

AGPL-3.0-or-later — see the LICENSE file for details.