codemagic-mcp

An MCP (Model Context Protocol) server that gives AI agents a unified surface over Codemagic CI/CD and App Store Connect / Google Play, enabling a complete mobile app delivery pipeline — from onboarding a repository through building, signing, and publishing — driven by conversation.

What it does

The server exposes tools across five domains:

• Codemagic — list teams and apps, trigger builds, wait for results, retrieve artifacts, fetch build logs, manage variable groups, caches, and webhooks
• App Store Connect — manage TestFlight, upload and submit builds, set listing text and screenshots, validate, submit, and release to the App Store
• Google Play — publish AABs, promote releases, manage staged rollouts, set listing text and screenshots, read and reply to user reviews
• Testing — parse JUnit XML test results from any Codemagic build; get a pass/fail/error/skip summary with per-failure details
• Cross-store — validate localized release notes against platform char limits and BCP-47 locale codes

The intended end-to-end flows are:

iOS: list_asc_builds → get_yaml_template → trigger_build → wait_for_build → upload_build_to_asc → set_version_metadata → validate_app_submission → submit_for_app_store_review → release_version

Android: get_latest_build_number → get_yaml_template → trigger_build → wait_for_build → upload_to_google_play → promote_google_play_release

Prerequisites

• Node.js 20 or 22 (LTS)
• asc CLI — asccli.sh — required for App Store Connect tools
• google-play CLI — part of codemagic-cli-tools — required for Google Play tools

  pip install codemagic-cli-tools

Environment variables

Required

| Variable | Description | |----------|-------------| | CODEMAGIC_API_TOKEN | Your Codemagic API token. Found in Codemagic → Account settings. |

App Store Connect tools (iOS)

| Variable | Description | |----------|-------------| | ASC_KEY_ID | App Store Connect API key ID | | ASC_ISSUER_ID | App Store Connect issuer ID | | ASC_PRIVATE_KEY_B64 | Base64-encoded .p8 private key (base64 -i AuthKey_XXXX.p8) | | ASC_BYPASS_KEYCHAIN | Set to 1 to force env var auth instead of the macOS keychain |

Google Play tools (Android)

| Variable | Description | |----------|-------------| | GOOGLE_PLAY_SERVICE_ACCOUNT_CREDENTIALS | Raw JSON content of your Google Play service account key file |

For the Google Play credentials you can use the @file: prefix to avoid pasting JSON inline:

GOOGLE_PLAY_SERVICE_ACCOUNT_CREDENTIALS=@file:/path/to/service-account.json

Installation

Using npx (recommended)

No installation needed. Add the server to your MCP client config with npx and it downloads and runs automatically:

"command": "npx",
"args": ["-y", "codemagic-mcp-server"]

See the Claude Desktop section below for the full config.

Global install

If you prefer a permanent install instead of npx:

npm install -g codemagic-mcp-server

Then use codemagic-mcp as the command in your MCP client config:

"command": "codemagic-mcp",
"args": []

Development

To build from source:

git clone https://github.com/todah-zg/codemagic-mcp.git
cd codemagic-mcp
npm install
npm run build

Then use the local path in your MCP config — see Running from a local clone below.

Running

MCP Inspector (development / testing)

Set the required environment variables in your shell, then:

npx @modelcontextprotocol/inspector node dist/index.js

Claude Desktop

Add to your claude_desktop_config.json:

If installed from npm

{
  "mcpServers": {
    "codemagic": {
      "command": "npx",
      "args": ["-y", "codemagic-mcp-server"],
      "env": {
        "CODEMAGIC_API_TOKEN": "your-token",
        "ASC_KEY_ID": "your-key-id",
        "ASC_ISSUER_ID": "your-issuer-id",
        "ASC_PRIVATE_KEY_B64": "base64-encoded-p8-key",
        "ASC_BYPASS_KEYCHAIN": "1",
        "GOOGLE_PLAY_SERVICE_ACCOUNT_CREDENTIALS": "@file:/path/to/service-account.json"
      }
    }
  }
}

If running from a local clone (development):

{
  "mcpServers": {
    "codemagic": {
      "command": "node",
      "args": ["/absolute/path/to/codemagic-mcp-server/dist/index.js"],
      "env": {
        "CODEMAGIC_API_TOKEN": "your-token",
        "ASC_KEY_ID": "your-key-id",
        "ASC_ISSUER_ID": "your-issuer-id",
        "ASC_PRIVATE_KEY_B64": "base64-encoded-p8-key",
        "ASC_BYPASS_KEYCHAIN": "1",
        "GOOGLE_PLAY_SERVICE_ACCOUNT_CREDENTIALS": "@file:/path/to/service-account.json"
      }
    }
  }
}

The config file is at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using with Claude Desktop

Connecting the server

To verify the server is connected, open a new conversation and ask: "ping the codemagic mcp server". If connected, Claude will call the ping tool and respond with "Codemagic MCP server is running." If not connected, check that the path in args is correct and that all required environment variables are set, then restart Claude Desktop with Cmd+Q (not just closing the window).

If the server does not appear, check that the CODEMAGIC_API_TOKEN environment variable is set correctly in the config and that the path to dist/index.js is absolute and correct.

Workflow prompts

Once connected, type / in the Claude Desktop input field to open the command picker. You will see five workflow prompts from this server:

| Prompt | When to use | |--------|-------------| | /onboarding | Starting from scratch — connect a repo, get a first build passing | | /android_release | Build a signed AAB and publish it to Google Play | | /ios_release | Build a signed IPA and upload it to TestFlight | | /first_publish_ios | One-time setup for first-time iOS App Store publishers — Apple Developer enrollment, app record, age rating, privacy labels | | /first_publish_android | One-time setup for first-time Google Play publishers — Play account, content rating, closed testing period |

Select a prompt and Claude will receive a step-by-step playbook and begin executing the workflow using the available tools.

Example conversations

You can also describe what you want in plain language — Claude will select the right tools automatically:

"I have a Flutter app at github.com/example/myapp. Set it up on Codemagic and get a first build running."

"Trigger a release build for my Android app, version 2.1.0. The last build number on Google Play was 41."

"What is the current App Store review status for my iOS app?"

Config file location

| Platform | Path | |----------|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

Tools

Codemagic

| Tool | Description | |------|-------------| | ping | Check that the server is running | | list_teams | List teams the authenticated account belongs to | | list_applications | List apps in your Codemagic account or team | | list_workflows | List workflows for an app | | list_builds | List builds with optional filters (app, status, branch, workflow) | | get_build | Get full details for a single build including artifacts | | get_build_logs | Fetch per-step log text for a build — by default returns failed steps only | | trigger_build | Trigger a build; optionally supply an inline codemagic.yaml or override instance_type | | wait_for_build | Single-check tool — returns status immediately; call again until terminal state | | cancel_build | Cancel a running or queued build | | add_application | Connect a Git repository to Codemagic; auto-generates SSH deploy keys for SSH URLs | | get_webhook_url | Get the incoming webhook URL to paste into your Git provider settings | | list_webhooks | List webhook subscriptions configured for an app | | delete_webhook | Delete a webhook subscription from an app | | list_caches | List build caches for an app | | delete_cache | Delete all caches or a specific cache by ID | | create_public_artifact_url | Create a time-limited public download URL for a build artifact |

App Store Connect (iOS)

| Tool | Description | |------|-------------| | list_asc_apps | List apps in App Store Connect | | list_asc_builds | List TestFlight builds for an app | | list_testflight_groups | List TestFlight beta groups | | get_asc_review_status | Get the App Store review state for an app | | get_asc_release_status | Full release pipeline dashboard (builds, TestFlight, App Store) | | upload_to_testflight | Download an IPA from Codemagic and upload to TestFlight | | submit_beta_review | Submit a TestFlight build for external beta review (required before external groups) | | add_testflight_tester | Add a tester by email to TestFlight, optionally to a group | | create_testflight_group | Create an internal or external TestFlight beta group | | set_export_compliance | Declare encryption usage for a build (required before App Store submission) | | set_version_metadata | Set "What's New" text and other per-locale metadata for an App Store version | | validate_app_submission | Preflight check — returns an ordered list of blockers before submission | | upload_build_to_asc | Upload an IPA to App Store Connect (fast, non-blocking); poll list_asc_builds until VALID | | submit_for_app_store_review | Attach a processed build to a version and submit for App Store review | | release_version | Release an approved App Store version immediately | | set_phased_release | Create, pause, resume, or complete a phased rollout | | get_ios_store_listing | Pull current App Store listing text for all locales (name, description, keywords, etc.) | | set_ios_store_listing | Update App Store listing text for a locale — only provided fields are changed | | list_ios_screenshot_types | List supported screenshot device types and their required pixel dimensions | | upload_ios_screenshots | Download screenshots from URLs and upload to App Store Connect for a device type and locale |

Google Play (Android)

| Tool | Description | |------|-------------| | list_google_play_tracks | List tracks (internal, alpha, beta, production) with release info | | list_google_play_bundles | List uploaded AABs by version code | | upload_to_google_play | Download an AAB from Codemagic and publish to a Google Play track | | get_latest_build_number | Get the highest version code across all (or specified) tracks | | promote_google_play_release | Promote a release between tracks (internal → alpha → beta → production) | | set_rollout_fraction | Expand, halt, or resume a staged rollout by setting the user fraction | | share_app_internally | Upload an AAB to Internal App Sharing for instant QA install links | | get_android_store_listing | Fetch current Google Play store listing for a language (title, descriptions) | | set_android_store_listing | Update Google Play store listing for a language — only provided fields are changed | | upload_android_screenshots | Download screenshots from URLs and upload to Google Play for a language and device type | | set_android_data_safety | Submit the data safety declaration CSV (exported from Play Console) — re-upload when data practices change | | list_google_play_reviews | List recent user reviews with optional star rating filter (e.g. 1–2 stars only); includes developer reply status and review IDs | | reply_to_google_play_review | Post or update a developer reply to a user review (max 350 characters) |

Testing

| Tool | Description | |------|-------------| | get_test_results | Fetch and parse JUnit XML test results from a Codemagic build — returns a pass/fail/error/skip summary with per-failure details and stack trace excerpts. Covers Flutter, Android instrumented tests, and iOS (via xcresult conversion). Pass artifact_url directly if you already have it from wait_for_build. |

Cross-store

| Tool | Description | |------|-------------| | prepare_release_notes | Validate localized release notes — checks BCP-47 locale codes and char limits (Android: 500, iOS: 4000) | | check_publish_readiness | Aggregate publish-readiness checks for iOS or Android. API-verifiable items (valid build, listing completeness, binary validation) run live; items with no API (age rating, privacy labels, legal agreements) are always listed as human-required. Each item is tagged as 'agent can fix' or 'human required'. |

Variable Groups

| Tool | Description | |------|-------------| | list_variable_groups | List variable groups for a team or app | | create_variable_group | Create a new variable group (team or app scoped) | | add_variable | Add a non-secret variable to a group | | list_variables | List variables in a group (required to get IDs before updating or deleting) | | update_variable | Update the name or value of a variable by ID | | delete_variable | Delete a variable from a group by ID |

YAML

| Tool | Description | |------|-------------| | validate_codemagic_yaml | Validate a codemagic.yaml against the official Codemagic JSON schema | | get_yaml_template | Get a starter codemagic.yaml for android, ios, flutter, flutter-native, react-native, ionic-capacitor, ionic-cordova, kmm, snap, unity, unity-oculus, dotnet-maui, ios-screenshots, android-screenshots, flutter-screenshots — plus android-debug, flutter-android-debug, react-native-android-debug for initial onboarding | | list_yaml_template_types | List all supported project types for get_yaml_template | | detect_project_type | Detect the project type from a repository file listing — returns the recommended template and debug template to start with |

Prompts

| Prompt | Description | |--------|-------------| | onboarding | Zero to first debug build — add repo, get template, trigger build, configure webhook | | android_release | Signed AAB from build to Google Play — build number, template, trigger, publish, promote | | ios_release | Signed IPA from build to App Store — build number, template, trigger, TestFlight, metadata, validate, submit, release | | first_publish_ios | One-time setup checklist for first-time iOS publishers — Apple Developer enrollment, app record, age rating, privacy labels, then hands off to /ios_release | | first_publish_android | One-time setup checklist for first-time Android publishers — Play account, content rating, closed testing period, then hands off to /android_release |

Prompts are reusable workflow playbooks. In Claude Desktop they appear as slash commands. An agent can also invoke them by name to get step-by-step instructions for a complete workflow.

Project structure

src/
  index.ts              — Server setup, env validation, transport
  codemagic.ts          — Codemagic API functions (v3 + v1)
  asc.ts                — App Store Connect CLI wrapper
  googleplay.ts         — Google Play CLI wrapper
  androidpublisher.ts   — Google Play androidpublisher REST API client (listings, screenshots, reviews)
  testing.ts            — JUnit XML parser (no external dependencies)
  ssh.ts                — SSH key generation and deploy key setup
  yaml.ts               — YAML validation logic
  templates.ts          — Static codemagic.yaml templates
  detection.ts          — Project type detection from repository file listings
  prompts.ts            — MCP prompt resources (workflow playbooks)
  tools/
    codemagic.ts        — Codemagic MCP tool registrations
    asc.ts              — App Store Connect MCP tool registrations
    googleplay.ts       — Google Play MCP tool registrations
    yaml.ts             — YAML MCP tool registrations
    releasenotes.ts     — Release notes validation tool
    readiness.ts        — Publish readiness check tool
    testing.ts          — Test results tool

The src/ modules contain pure functions (API calls, CLI wrappers) with no MCP dependency. The src/tools/ modules wire those functions up as MCP tools — input schemas, formatting, error responses.

Notes

• Inline YAML: trigger_build accepts an optional yaml_content parameter. When provided, the YAML is uploaded alongside the build request and does not need to exist in the repository. Useful for agent-generated configurations.
• Build numbers: Templates use $BUILD_NUMBER and $VERSION_NAME as plain variables — no store lookups happen inside the YAML. The agent determines the correct values via list_asc_builds or list_google_play_tracks before triggering, then passes them through the variables parameter of trigger_build.
• Signing: iOS signing happens on the Codemagic build machine (macOS + keychain). The MCP server never handles signing identities directly.
• Team vs. personal account: list_applications and list_builds accept an optional team_id. Without it, they operate on the authenticated user's personal account.
• Variable groups and secrets: add_variable only creates non-secret variables. Secret values (API keys, certificates, tokens) should be added directly in the Codemagic UI — secrets should never pass through the agent. Once set up, reference groups by name in trigger_build via the groups parameter.