Minimal MCP server for discovering Xcode Cloud products, inspecting and editing workflows, monitoring build runs, and retrieving build issues, logs, test summaries, and UI test artifacts through the App Store Connect API.

Build lookup is workflow-scoped. Retrieval tools accept a direct buildRunId, or a workflowId plus buildNumber, or a workflowId plus buildSelector: "latest" | "latestFailing".

list_products and list_workflows automatically paginate through all results.

list_build_runs supports status: "all" | "failed" | "succeeded" | "running" | "pending" and an optional limit, which defaults to 20, so agents can poll active workflows without post-processing every run locally or inflating MCP response size.

• Node.js 20+
• App Store Connect API credentials with access to Xcode Cloud

Primary names:

• APPSTORE_CONNECT_API_KEY_ID
• APPSTORE_CONNECT_API_ISSUER_ID
• APPSTORE_CONNECT_API_KEY_CONTENT

Compatibility aliases:

• APP_STORE_KEY_ID
• APP_STORE_ISSUER_ID
• APP_STORE_PRIVATE_KEY

The private key can be passed as literal multi-line PEM content or as a string with escaped \n.

claude mcp add xcode-cloud \
  --env APPSTORE_CONNECT_API_KEY_ID="$APPSTORE_CONNECT_API_KEY_ID" \
  --env APPSTORE_CONNECT_API_ISSUER_ID="$APPSTORE_CONNECT_API_ISSUER_ID" \
  --env APPSTORE_CONNECT_API_KEY_CONTENT="$APPSTORE_CONNECT_API_KEY_CONTENT" \
  -- npx -y @thatfactory/xcode-cloud-mcp

codex mcp add xcode-cloud \
  --env APPSTORE_CONNECT_API_KEY_ID="$APPSTORE_CONNECT_API_KEY_ID" \
  --env APPSTORE_CONNECT_API_ISSUER_ID="$APPSTORE_CONNECT_API_ISSUER_ID" \
  --env APPSTORE_CONNECT_API_KEY_CONTENT="$APPSTORE_CONNECT_API_KEY_CONTENT" \
  -- npx -y @thatfactory/xcode-cloud-mcp

• list_products()
• list_workflows(productId)
• get_workflow_details(workflowId)
• list_build_runs(workflowId, limit?, status?)
• set_workflow_enabled(workflowId, enabled)
• update_workflow_general(workflowId, name?, description?, clean?)
• update_workflow_start_conditions(workflowId, branchStartCondition?, manualBranchStartCondition?, pullRequestStartCondition?, manualPullRequestStartCondition?, scheduledStartCondition?, tagStartCondition?, manualTagStartCondition?)
• update_workflow_actions(workflowId, actions)
• get_build_issues(buildRunId? workflowId? buildNumber? buildSelector?)
• get_build_logs(buildRunId? workflowId? buildNumber? buildSelector?, maxCharacters?)
• materialize_build_logs(buildRunId? workflowId? buildNumber? buildSelector?)
• get_test_results(buildRunId? workflowId? buildNumber? buildSelector?)
• get_failed_tests(buildRunId? workflowId? buildNumber? buildSelector?)
• get_test_artifacts(buildRunId? workflowId? buildNumber? buildSelector?)
• cleanup_saved_logs(buildRunId?, maxAgeHours?)

get_build_logs keeps the MCP response compact on purpose:

• it downloads and extracts text-like build log artifacts to a temporary local directory
• it returns savedLogsDirectory and savedLogs so local agents can inspect the extracted files with rg, grep, or cat
• it returns a compact failedTests summary, highlights, and a capped excerpt
• even if a caller passes a very large maxCharacters, the inline excerpt is clamped to avoid oversized MCP responses

Recommended agent workflow:

1. Call get_failed_tests or get_build_logs.
2. Read savedLogsDirectory.
3. Use rg inside that directory to inspect the exact failing test or assertion.
4. If needed, call cleanup_saved_logs when the investigation is done.

Temporary logs are written under the system temp directory in a path like:

/tmp/xcode-cloud-mcp/build-logs/<buildRunId>

On macOS this typically resolves to a path under /var/folders/.../T/.

Cleanup policy:

• each new call for the same buildRunId deletes and recreates that build-specific temp directory first
• older build directories are pruned automatically when they are older than 24 hours
• you can also call cleanup_saved_logs directly for one buildRunId or for all directories older than a chosen retention window

Retrieve logs of the latest failing build for workflow abc123.

Retrieve logs of build 81, then inspect the returned savedLogsDirectory and grep for Expectation failed.

Get the failed tests for build 81, then open the saved logs directory and inspect the failing test in context.

Retrieve logs of build number 42 for workflow abc123.

Show me the latest failing UI test artifacts for workflow abc123.

List the workflows for product def456 and then summarize the latest build.

Show me the full workflow details for workflow abc123, including environment, start conditions, actions, and whether it is enabled.

Disable workflow abc123, remove the archive action, then restore the original action list after the experiment.

get_workflow_details returns the live workflow configuration exposed by App Store Connect, grouped into:

• general
• environment
• startConditions
• actions
• postActions

Notes:

• environment includes repository, xcodeVersion, and macOsVersion when App Store Connect returns them.
• actions includes action type, scheme, platform, destination, required-to-pass state, and test-plan details when present.
• postActions is currently returned as an empty array with a note because the App Store Connect workflow payload does not expose separate post-actions in the observed API response.

The workflow update tools are intentionally explicit:

• set_workflow_enabled only toggles isEnabled
• update_workflow_general only changes name, description, and clean
• update_workflow_start_conditions only changes the start-condition objects you pass
• update_workflow_actions replaces the full actions array, so callers should fetch the current workflow first and then send the final desired action list

Important restriction:

• if the workflow has Restrict Editing enabled in Xcode Cloud, edits can fail even when the App Store Connect API key has App Manager access
• for MCP edits to work reliably, disable the Restrict Editing checkbox for that workflow before using the write tools
• if Apple still rejects the request after that, use a stronger API key role such as Admin

Install dependencies:

npm install

Run tests:

npm test

Build the package:

npm run build