app-store-connect-mcp 0.1.0

Add your description here

App Store Connect MCP Server

Talk to App Store Connect about your app. Modular tools, async I/O, and OpenAPI‑driven typing keep your agent accurate as Apple evolves.

Why this is different

• Spec‑aware: Fields and enums are derived from Apple’s OpenAPI spec at runtime, reducing drift and surprise breakage.
• Fast by default: Async httpx client, server‑side filtering, and smart pagination to keep payloads lean.
• Smart filtering: Server‑side + client‑side filtering with chainable filter engine for complex queries.
• Modular domains: Clean separation of tool schemas and handlers; add new domains without touching the core; optimized LLM discovery/ usage
• MCP‑native: Stdio transport, capability declarations, and tool wiring align with the official SDK python‑sdk README.

Quick start

Install from source:

git clone https://github.com/gjeltep/app-store-connect-mcp.git
cd app-store-connect-mcp
uv pip install -e ".[dev]"

Configuration

Set these environment variables:

# Required
export APP_STORE_KEY_ID="YOUR_KEY_ID"
export APP_STORE_ISSUER_ID="YOUR_ISSUER_ID"
export APP_STORE_PRIVATE_KEY_PATH="/path/to/AuthKey_XXXXX.p8"

# Optional
export APP_STORE_APP_ID="YOUR_APP_ID"
export APP_STORE_KEY_TYPE="team"  # or "individual"

Usage

Run with your environment variables set (recommended):

app-store-connect-mcp

Or use a .env file during development:

# Copy and configure .env file
cp .env.example .env
# Edit .env with your credentials

# Run with --env-file flag
app-store-connect-mcp-dev --env-file .env

# Validate configuration without starting server
app-store-connect-mcp-dev --env-file .env --validate-only

Use with any MCP‑compatible client; the server announces tools and handles calls over stdio.

Generate or update API models

Models are generated from Apple's official OpenAPI spec. You can override the source with APP_STORE_CONNECT_OPENAPI_URL.

uv pip install -e .[dev]
python scripts/generate_models.py

Development

See CONTRIBUTING.md for test, lint, formatting, and local tooling guidance.

Tools

Tools use a resource-first naming convention (resource.verb) with category tags for discoverability.

App Tools

• reviews.list: List customer reviews with filters (rating, territory, appStoreVersion).
• reviews.search: Advanced search with rating ranges, territory matching, date windows, and content search.
• reviews.get: Get detailed review information.

TestFlight Tools

• crashes.list: List crash submissions from beta testers with filters (device_model, os_version, app_platform, device_platform, build_id, tester_id).
• crashes.search: Advanced search with:
  • Server‑side filters (appPlatform, deviceModel, osVersion)
  • Post‑filters: OS ranges (min/max), device model substrings (e.g., "iPhone 15"), and date windows (created_since_days, created_after, created_before).
• crashes.get_by_id: Get detailed information about a specific crash submission.
• crashes.get_log: Retrieve the raw crash log text for a specific submission.

Analytics Tools

Requests:

• analytics_report_requests.list: List analytics report requests for an app with filters (access_type).
• report_requests.create: Create new analytics report requests for specific metrics and timeframes.
• report_requests.get: Get detailed information about a specific analytics report request.

Reports:

• report_requests.list_reports: List available reports within a request with filters (name, category).
• reports.get: Get specific analytics report information.
• reports.list_instances: List report instances with filters (granularity, processing_date).
• report_instances.get: Get detailed information about a specific report instance.

Segments:

• report_instances.list_segments: List data segments for a report instance.
• report_segments.get: Get segment download information (checksum, URL, size).
• report_instances.download_data: Download analytics report data to a TSV file.

Xcode Cloud Tools

Products & Workflows:

• products.list: List all Xcode Cloud products with filters (product_type).
• products.get: Get detailed information about a specific product.
• workflows.list: List workflows for a product with filters (is_enabled).
• workflows.get: Get detailed workflow information (note: create/update/delete operations not supported for safety).

Builds:

• builds.list: List builds for a product or workflow with filters (execution_progress, completion_status, is_pull_request_build).
• builds.get: Get detailed build information including status, duration, and issue counts.
• builds.start: Start a new build for a workflow with optional branch/tag or pull request specification.

Build Artifacts & Results:

• artifacts.list: List downloadable artifacts for a build.
• issues.list: List issues (errors, warnings) for builds or workflows.
• test_results.list: List test results including status, duration, and failure messages.

SCM Integration:

• scm_providers.list: List configured SCM providers (GitHub, GitLab, Bitbucket).
• repositories.list: List Git repositories for an SCM provider.
• pull_requests.list: List pull requests for a repository.
• git_references.list: List branches and tags for a repository.

Architecture

graph TD
    %% Entry Point
    subgraph "Entry Point"
        SERVER[server.py<br/>MCP stdio server]
    end

    %% Domain Implementations
    subgraph "Domain Handlers"
        TESTFLIGHT[testflight/handlers.py<br/>TestFlight crash<br/>management]
        APP[app/handlers.py<br/>App Store review<br/>management]
        ANALYTICS[analytics/handlers.py<br/>Analytics report<br/>management]
        XCODE_CLOUD[xcode_cloud/handlers.py<br/>Xcode Cloud CI/CD<br/>management]
    end

    %% Core Architecture
    subgraph "Core Components"
        subgraph "Core Framework"
            PROTOCOLS[protocols.py<br/>Abstract interfaces]
            BASE_HANDLER[base_handler.py<br/>Abstract base class]
            QUERY_BUILDER[query_builder.py<br/>Fluent query construction]
            FILTERS[filters.py<br/>Chainable filter engine]
            RESPONSE_HANDLER[response_handler.py<br/>API response processing]
            CONTAINER[container.py<br/>Dependency injection]
            ERRORS[errors.py<br/>Structured error handling]
        end

        subgraph "API Layer"
            ASC_CLIENT[app_store_connect.py<br/>App Store Connect client<br/>with JWT auth]
            HTTP_CLIENT[http_client.py<br/>Base HTTP client]
            MODELS[app_store_connect_models.py<br/>Auto-generated Pydantic<br/>models from OpenAPI spec]
        end

        subgraph "Data & Tools"
            OPENAPI[app_store_connect_api_openapi.json<br/>Apple's OpenAPI spec]
            GENERATE_SCRIPT[scripts/generate_models.py<br/>Model generation script]
        end
    end

    %% Vertical Stack Relationships
    SERVER -->|"routes to"| ANALYTICS
    ANALYTICS -->|"uses"| ASC_CLIENT

    %% Styling
    classDef entry fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef core fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef domain fill:#fce4ec,stroke:#880e4f,stroke-width:2px

    class SERVER entry
    class PROTOCOLS,BASE_HANDLER,QUERY_BUILDER,FILTERS,RESPONSE_HANDLER,CONTAINER,ERRORS,ASC_CLIENT,HTTP_CLIENT,MODELS,OPENAPI,GENERATE_SCRIPT core
    class TESTFLIGHT,APP,ANALYTICS,XCODE_CLOUD domain

Credits

Built on the official Model Context Protocol Python SDK — see the docs and examples in the python‑sdk README.

—

See CONTRIBUTING.md if you’d like to help.