codemagic-mcp

Unofficial community MCP server for the Codemagic API. The project name is codemagic-mcp; it is not a Codemagic product.

Disclaimer. This is an independent, community-built project. It is not made, endorsed, supported, or reviewed by Codemagic or Nevercode Ltd. "Codemagic" is a trademark of Nevercode Ltd and is used here only to describe which public API this server talks to. Nothing in this repository is official. Use it at your own risk, and direct Codemagic product questions to Codemagic, not to this project.

A standard Model Context Protocol server, over stdio, for the public Codemagic REST API. Point any MCP-capable client at it (Claude Code, Codex, Cursor, Claude Desktop, or anything else that can launch a local mcpServers command) to list apps and teams, inspect build history, and optionally trigger or cancel builds and manage team settings. Each installation uses the user's own Codemagic API token. Nothing is hosted, and no shared credentials or company-specific IDs are bundled.

The same code is also packaged as a Codex plugin for people who prefer installing from a local plugin marketplace. That is an optional packaging on top of the plain MCP server, not a different product.

Status: 0.x, pre-1.0. Core read-only operations (apps, teams, build history) have been verified against a live account. Administrative operations are covered by test fixtures rather than live mutations. Published to npm as @alikayhan/codemagic-mcp; not listed in any public plugin directory. See CHANGELOG.md.

Requirements

• Node.js 22 or newer on your PATH. It ships npx, which is all the default install needs.

• A personal Codemagic API token. Codemagic's docs currently place it under Teams → Personal Account → Integrations → Codemagic API → Show. Permissions follow the token owner's team role.

Related MCP server: codemagic_mcp

Quick start

The server is published to npm as @alikayhan/codemagic-mcp. Clients launch it with npx -y @alikayhan/codemagic-mcp, which downloads it on first use and caches it. Nothing needs to be cloned or built. The name is scoped because unscoped codemagic-mcp collides with other packages on npm; the project itself is still called codemagic-mcp.

1. Save your token privately

npx -y @alikayhan/codemagic-mcp configure

This prompts for the token without echoing it and writes it to ~/.config/codemagic-mcp/credentials.env (directory mode 0700, file mode 0600 on macOS/Linux). Do not paste the token into a chat, a command argument, or a client config file. Alternatively, supply CODEMAGIC_API_TOKEN through your client's environment configuration; environment values override the saved file. The server never reads a .env from the current directory or from a repository.

Without a token the server still starts, but in setup mode: it exposes a single tool, cm_setup_status, which returns the configure command and the credentials file location, and no API tools. Reconnect the server after running configure and the full tool list appears.

2. Connect your MCP client

Claude Code

claude mcp add --scope user codemagic -- npx -y @alikayhan/codemagic-mcp

Then run /mcp inside Claude Code to confirm it connected. Tools appear as mcp__codemagic__cm_list_teams and so on.

Codex

codex mcp add codemagic -- npx -y @alikayhan/codemagic-mcp

This writes an [mcp_servers.codemagic] entry to ~/.codex/config.toml. To set mode or toolset there instead of through configure, add an [mcp_servers.codemagic.env] table with CODEMAGIC_MODE and CODEMAGIC_TOOLSET.

Pi

pi mcp add codemagic -- npx -y @alikayhan/codemagic-mcp

OpenCode (opencode.json)

{
  "mcp": {
    "codemagic": {
      "type": "local",
      "command": ["npx", "-y", "@alikayhan/codemagic-mcp"]
    }
  }
}

Any client that accepts mcpServers JSON (Cursor, Claude Desktop, Windsurf, and others)

{
  "mcpServers": {
    "codemagic": {
      "command": "npx",
      "args": ["-y", "@alikayhan/codemagic-mcp"]
    }
  }
}

Desktop clients on Windows sometimes cannot launch npx directly; use "command": "cmd" with "args": ["/c", "npx", "-y", "@alikayhan/codemagic-mcp"]. If the client does not inherit your shell environment and you prefer an env file over the saved credentials, add "--env-file=/absolute/path/codemagic.env" after @alikayhan/codemagic-mcp in args. See .env.example for the file format.

To pin a version, write @alikayhan/codemagic-mcp@0.1.0 instead of @alikayhan/codemagic-mcp. For faster startup, install once with npm install -g @alikayhan/codemagic-mcp and use codemagic-mcp as the command with no arguments.

3. Try it

Ask your agent: "List my Codemagic teams and their apps, then show the latest builds."

By default the server can read everything and can start or cancel builds, delete caches and create artifact links. Starting a build can cost money and, depending on the workflow, publish a release. See Toolsets and permissions to restrict it to read-only or to enable administrative writes.

Other ways to run the server

Two alternatives exist for people who do not want npm involved at runtime. In the instructions above, replace npx -y @alikayhan/codemagic-mcp with node SERVER, where SERVER is:

The release ZIP also contains a local Codex plugin marketplace for people who prefer installing the server as a Codex plugin; see INSTALL.md. Do not combine the plugin with a codex mcp add entry in the same client, or the tools appear twice.

Setup prompt for a coding agent

Paste the following into Claude Code, Codex, Pi, Cursor, or any other coding agent. The agent registers the server and verifies it, but leaves the token to you: it must never ask for or handle it, and you enter it yourself in a terminal.

Set up codemagic-mcp, an unofficial community MCP server for the Codemagic API. It is published on npm as `@alikayhan/codemagic-mcp` and documented at https://github.com/alikayhan/codemagic-mcp

This is an unofficial, community-built MCP server, not an official Codemagic product. It is a standard stdio MCP server that runs locally with my own Codemagic API token. Clients launch it with `npx -y @alikayhan/codemagic-mcp`.

1. Confirm Node.js 22 or newer is on PATH (`node --version`). If not, stop and tell me how to install it.

2. Verify the package runs: `npx -y @alikayhan/codemagic-mcp --version` must print a version. Do not clone the repository or install anything globally unless I ask.

3. Check whether credentials are already saved: `~/.config/codemagic-mcp/credentials.env` (or `$CODEMAGIC_CONFIG_DIR/credentials.env`). Report only whether the file exists. Never read, print, or ask me for the token. If it does not exist, tell me to run `npx -y @alikayhan/codemagic-mcp configure` myself in a terminal and paste my Codemagic API token at its hidden prompt, then wait until I say it is done. Until then the server runs in setup mode and exposes only `cm_setup_status`.

4. Register the server in the MCP client you are running in, with the server name `codemagic`, the command `npx`, and the arguments `-y @alikayhan/codemagic-mcp`:
   - Claude Code: `claude mcp add --scope user codemagic -- npx -y @alikayhan/codemagic-mcp`
   - Codex: `codex mcp add codemagic -- npx -y @alikayhan/codemagic-mcp`
   - Pi: `pi mcp add codemagic -- npx -y @alikayhan/codemagic-mcp`
   - OpenCode: add `"codemagic": { "type": "local", "command": ["npx", "-y", "@alikayhan/codemagic-mcp"] }` under `mcp` in `opencode.json`.
   - Cursor, Claude Desktop, Windsurf, or others: add `"codemagic": { "command": "npx", "args": ["-y", "@alikayhan/codemagic-mcp"] }` under `mcpServers` in the client's MCP config file. Ask me which client if you cannot tell.
   Do not put any token or environment secret into the config. Do not change or remove other MCP entries.

5. If the client supports it, reconnect MCP servers and confirm a `codemagic` server appears. If its only tool is `cm_setup_status`, the token is missing: call it, relay the steps to me, and wait. If tools such as `cm_list_teams` appear, setup is complete. If a restart is required, tell me.

6. Report what you did, the exact config you added, and which of these follow-ups I can choose: by default the server can read everything plus start/cancel builds, delete caches and create artifact links; `npx -y @alikayhan/codemagic-mcp configure --mode read-only` restricts it to inspection, `--mode all` adds administrative writes, and `--toolset all` exposes the full API. Do not run those for me.

Coverage

106 tools: 98 mappings from Codemagic's public v3 OpenAPI contract and 8 documented legacy operations. The contract is bundled, so startup does not download a schema or silently expose new operations. See the complete coverage table.

This is API coverage, not full web UI parity. Raw build-log streaming, artifact binary downloads/uploads, signing-file uploads, repository YAML editing, and undocumented browser endpoints are not implemented. cm_get_build_actions returns action metadata/scripts, not console logs. API-token retrieval/revocation is intentionally excluded so a tool cannot expose or invalidate the server's own credential. Secret response fields (including newly created access keys and VNC passwords) are redacted; retrieve those through Codemagic's UI when needed.

The workflow endpoint reports workflows known to Codemagic. If a newly added YAML workflow is absent, obtain its ID from the repository's codemagic.yaml and pass it explicitly. Store deployment behavior belongs to the selected workflow: triggering a build can also publish a release.

Toolsets and permissions

Set these through your client's environment configuration, or persist mode and toolset alongside the token:

npx -y @alikayhan/codemagic-mcp configure --mode read-only --toolset core

Press Enter at the token prompt to keep the saved token. Reconnect or restart the client after changing configuration.

Toolset and mode are independent. core + read-only is the safest setting for shared or untrusted agents. all + read-only exposes broader inspection without mutations. all + all also permits billing, membership, secret, deletion, invitation, and sharing operations. Disabled tools are absent from the MCP catalog and cannot be invoked by name. These are local exposure controls, not replacements for Codemagic's server-side permissions or your MCP client's approvals.

Examples

Ask your agent to list teams and apps first. Arguments are grouped into path, query, and body to avoid collisions. Optional pagination and filters belong in query; response pagination fields are preserved rather than automatically fetching every page.

List builds:

{
  "name": "cm_list_builds",
  "arguments": {
    "path": { "team_id": "YOUR_TEAM_ID" },
    "query": { "app_id": "YOUR_APP_ID", "branch": "main", "page_size": 10 }
  }
}

Start a build (available in the default builds mode):

{
  "name": "cm_start_build",
  "arguments": {
    "path": { "app_id": "YOUR_APP_ID" },
    "body": { "workflow_id": "ios-release", "branch": "main" }
  }
}

Exactly one of branch or tag is required. Build inputs, labels, instance type and environment overrides are accepted according to the bundled schema. V3 body keys use snake_case. The legacy app/artifact endpoints retain their documented camelCase keys.

Inspect a build or cancel it:

{ "name": "cm_get_build", "arguments": { "path": { "build_id": "YOUR_BUILD_ID" } } }

{ "name": "cm_cancel_build", "arguments": { "path": { "build_id": "YOUR_BUILD_ID" } } }

Use the codemagic://capabilities MCP resource to inspect enabled tools and contract provenance. For cm_create_artifact_link, use the literal path after /artifacts/ in the authenticated artifact URL and an explicit future expiresAt Unix timestamp. Encoded path input is rejected; supply literal names, including spaces.

Reliability and data handling

• Requests only go to fixed Codemagic origins. Redirects and arbitrary URL input are rejected to prevent forwarding the token elsewhere.

• Requests have timeouts and a 2 MiB response limit. Reduce page_size or filter more narrowly if a response is too large. Large audit CSV exports can exceed this limit.

• Mutations are never retried automatically. A transport failure or server error may leave an unknown outcome; inspect current state before retrying a build or billing action.

• HTTP 401/403 errors distinguish authentication from permissions. HTTP 429 responses include rate-limit headers; ratelimit-reset is seconds remaining. The client does not retry or sleep automatically.

• Structured results retain status, data and rate-limit metadata. HTTP 208 on cancellation means the build already finished; HTTP 202 cache deletion is asynchronous.

• Error bodies are suppressed because they can echo credentials. Known credential fields and exact API-token echoes are redacted. This is best-effort redaction, not a general secret detector: scripts, URLs, plaintext variables, and audit data may contain sensitive content. Tool arguments are visible to the MCP client and may be retained in its history; use a trusted client for secret-changing operations.

• stdout is reserved for MCP traffic during normal operation. No HTTP listener, filesystem-write tool, shell-execution tool, or unrestricted HTTP tool is exposed.

• This is a stdio server: one local process and one credential per client. It is not a hosted multi-user HTTP service and does not implement OAuth. Other users install their own copy.

Versioning and releases

Versions follow Semantic Versioning. While the major version is 0, minor releases may change tool names, argument shapes, or configuration; patch releases are fixes only. Every release has a dated section in CHANGELOG.md, following Keep a Changelog.

package.json is the only place the version is typed. src/version.js reads it, and scripts/sync-version.js copies it into plugin.json. The build and the test suite both fail if the three disagree or if the changelog lacks a section for the current version.

To cut a release:

1. Move the notes under ## [Unreleased] in CHANGELOG.md into a new ## [x.y.z] - YYYY-MM-DD section and update the link references at the bottom.

2. Run npm version minor (or patch / major). This bumps package.json, syncs plugin.json, commits, and creates the vx.y.z tag.

3. Run git push --follow-tags.

The Release GitHub Actions workflow runs on v* tags. It checks that the tag matches package.json, runs checks and tests, builds the Codex plugin ZIP and the npm tarball, attaches them to a GitHub Release whose body is that version's changelog section, and publishes the package to npm with provenance. Publishing uses npm trusted publishing tied to this repository's release.yml, so no npm token is stored in GitHub. Build outputs (dist/, release/, *.tgz) are gitignored and never committed.

Development

npm ci --ignore-scripts
npm run check
npm test
node src/cli.js --help

Source is standard JavaScript ESM with no compilation step. Tests do not need credentials or start real builds.

Bundle and package the Codex plugin:

npm run build
npm run test:plugin

Output: release/codemagic-plugin-0.1.0.zip, its SHA-256 file, and an extracted local marketplace. The ZIP contains a single-file dist/server.mjs with dependencies bundled, plus plugin.json and mcp.json in the portable Agent Plugins format. The bundled file is also a convenient target for non-Codex clients.

npm tarball: npm pack creates alikayhan-codemagic-mcp-0.1.0.tgz, the same artifact the release workflow publishes to npm. Install it with npm install -g /path/to/alikayhan-codemagic-mcp-0.1.0.tgz to try the published layout before cutting a release.

Updating the API contract: run npm run schema:update, or node scripts/update-schema.js /path/to/openapi.json with a downloaded specification. Review the generated diff, permissions and names, then run checks and tests. The schema is never refreshed at server startup. The generator resolves local references, uses strict object fields, and normalizes upstream overlapping oneOf type unions into anyOf (notably integer/number build inputs). Build branch/tag exclusivity is validated separately.

The test suite exercises MCP discovery and calls, stdio startup, request routing, validation, mode restrictions, pagination, timeout and error behavior, and credential handling. Administrative writes and non-macOS runtime behavior still need live acceptance testing.

Contributing, security and support

Contributions are welcome. CONTRIBUTING.md covers the development setup, the test and schema workflow, and what a pull request needs (a changelog entry, passing checks, no credentials in fixtures). Pull requests are squash-merged, and the PR title becomes the commit message on main.

Report security issues privately through GitHub's vulnerability reporting rather than in a public issue. SECURITY.md describes what is in scope and how token handling is designed. Never include an API token in an issue, log, or screenshot; redact it and revoke it in Codemagic if it was exposed.

For bugs and questions use the issue tracker. This is a volunteer project with no service-level commitment. Codemagic itself provides no support for it.

Sources and license

• Codemagic v3 API and OpenAPI specification

• Legacy applications, build cancellation, caches, and artifact links

• Model Context Protocol TypeScript SDK

Implementation code is MIT licensed. See LICENSE and NOTICE for upstream attribution. The bundled API contract is derived from Codemagic's published OpenAPI document and remains subject to Codemagic's own terms.

This project has no relationship with Codemagic or Nevercode Ltd. It is not an official integration, and Codemagic provides no support for it.