CodemagicMcp

Codemagic MCP 服务

一个本地 Python MCP 服务，将 Codemagic CI/CD REST API 封装为可由 Claude 调用的工具。无需离开聊天界面，即可从 Claude Code 或 Claude Desktop 触发构建、管理应用、下载构建产物和清除缓存。

工具

应用

工具	说明
list_apps	列出 Codemagic 账户中的所有应用
get_app	获取指定应用的详细信息
add_app	将公开仓库添加到 Codemagic
add_private_app	使用 SSH 密钥添加私有仓库
delete_app ⚠️	从 Codemagic 删除应用

构建

工具	说明
list_builds	列出构建，可按应用筛选
get_build	获取构建详情及步骤数量摘要；传入 include_steps=True 可获取完整步骤列表
trigger_build	为应用触发新构建
cancel_build ⚠️	取消正在运行的构建
get_build_logs	获取构建的逐步状态摘要（可按状态筛选）
get_step_logs	内联获取原始日志，或为指定构建步骤创建／更新受管理的临时文件
get_step_log_artifact	检查指定构建步骤的受管理本地步骤日志构建产物是否仍然存在
list_build_artifacts	列出构建生成的所有构建产物

构建产物

工具	说明
get_artifact_url	获取构建产物的下载 URL
create_artifact_public_url	为构建产物创建有时限的公开 URL

缓存

工具	说明
list_caches	列出应用的所有构建缓存
delete_cache ⚠️	删除指定的构建缓存
delete_all_caches ⚠️	删除应用的所有构建缓存

环境变量

工具	说明
list_variables	列出应用的所有环境变量
add_variable	为应用添加环境变量
update_variable	更新现有环境变量
delete_variable ⚠️	删除环境变量

Webhook

工具	说明
list_webhooks	列出应用的所有 webhook
add_webhook	为应用添加 webhook
delete_webhook ⚠️	删除 webhook

⚠️ 这些工具标记为具有破坏性，执行前会请求确认。

快速开始

通过 Claude Code 快速启动，无需单独安装：

# 1. Add the server (uses uvx to run it on-demand)
claude mcp add codemagic -e CODEMAGIC_API_KEY=your-api-key-here -- uvx codemagic-mcp

# 2. Restart Claude Code — tools will appear in /tools

就是这么简单。有关 CODEMAGIC_DEFAULT_APP_ID 等可选设置，请参阅配置。

---

安装

要求： Python 3.11+

选项 1 — uvx（推荐，无需安装）

uvx codemagic-mcp

选项 2 — pip

pip install codemagic-mcp

选项 3 — 从源代码安装

git clone https://github.com/AgiMaulana/CodemagicMcp.git
cd CodemagicMcp
python3 -m venv .venv
.venv/bin/pip install -e .

配置

从 Codemagic 用户设置 → 集成 → Codemagic API 获取 API 令牌。

可以通过环境变量或 .env 文件提供设置：

# .env
CODEMAGIC_API_KEY=your-api-key-here

# Optional: set a default app so you don't have to specify it every time
CODEMAGIC_DEFAULT_APP_ID=your-app-id-here

# Optional: customize managed temp log storage for get_step_logs(..., delivery="file")
CODEMAGIC_LOG_TEMP_DIR=/tmp/codemagic-mcp
CODEMAGIC_LOG_TTL_SECONDS=3600
CODEMAGIC_LOG_CLEANUP_INTERVAL_SECONDS=300
CODEMAGIC_LOG_MAX_TOTAL_BYTES=524288000
CODEMAGIC_LOG_MAX_FILE_COUNT=200

默认应用 ID

如果你主要使用一个应用，建议设置 CODEMAGIC_DEFAULT_APP_ID（此项可选）。设置后，每当工具需要 app_id 而你未指定时，AI 都会自动使用该 ID。如果未设置，AI 将：

1. 调用 list_apps 以查找可用应用。
2. 如果只有一个应用，则自动使用该应用。
3. 如果找到多个应用，则显示列表并请你选择。

步骤日志文件交付

get_step_logs 支持两种交付模式：

• delivery="file" 是默认模式，会将日志写入受管理的本地临时文件，并返回 artifact_id、file_path、bytes、line_count 和 expires_at 等元数据。
• delivery="inline" 会直接返回原始步骤日志文本。

当步骤日志过大、不适合直接返回时，本地文件模式会很有用。受管理的日志文件存储在 CODEMAGIC_LOG_TEMP_DIR 下；每当写入新日志文件时，系统都会择机清理已过期文件。默认保留时长由 CODEMAGIC_LOG_TTL_SECONDS 控制，默认为 3600 秒。

服务还会在启动时执行一次清理，并定期在后台循环清理。循环间隔由 CODEMAGIC_LOG_CLEANUP_INTERVAL_SECONDS 控制，默认为 300 秒。作为额外的安全措施，受管理的临时目录会受 CODEMAGIC_LOG_MAX_TOTAL_BYTES 和 CODEMAGIC_LOG_MAX_FILE_COUNT 限制；超过任一限制时，系统会优先删除最旧的文件。

get_step_log_artifact(build_id, step_id) 会检查受管理的工件是否仍然存在，而不会再次调用 Codemagic，也不会返回文件内容。工件元数据包含一个确定性的 artifact_id，格式如下：

artifact_<build_id>_<step_id>

如果工件不存在，服务会返回 status="missing"，并附带原因 not_generated_or_expired，这表示文件从未生成，或已过期并被删除。

在 Claude Code 中注册

运行以下命令以添加服务：

claude mcp add codemagic -- codemagic-mcp

然后在 MCP 环境配置中设置 API 密钥，或在启动 Claude Code 前在 shell 中导出该密钥：

export CODEMAGIC_API_KEY=your-api-key-here

或者，手动将其添加到 ~/.claude.json：

{
  "mcpServers": {
    "codemagic": {
      "command": "codemagic-mcp",
      "env": {
        "CODEMAGIC_API_KEY": "your-api-key-here",
        "CODEMAGIC_DEFAULT_APP_ID": "your-app-id-here"
      }
    }
  }
}

使用 uvx（无需预先安装）

{
  "mcpServers": {
    "codemagic": {
      "command": "uvx",
      "args": ["codemagic-mcp"],
      "env": {
        "CODEMAGIC_API_KEY": "your-api-key-here",
        "CODEMAGIC_DEFAULT_APP_ID": "your-app-id-here"
      }
    }
  }
}

重启 Claude Code，即可在 /tools 中看到这些工具。

在 Claude Desktop 中注册

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "codemagic": {
      "command": "codemagic-mcp",
      "env": {
        "CODEMAGIC_API_KEY": "your-api-key-here",
        "CODEMAGIC_DEFAULT_APP_ID": "your-app-id-here"
      }
    }
  }
}

重启 Claude Desktop 以应用更改。

项目结构

codemagic_mcp/
├── config.py        # pydantic-settings config (validates API key at startup)
├── client.py        # httpx async client, one method per endpoint
├── server.py        # FastMCP instance
└── tools/
    ├── apps.py
    ├── builds.py
    ├── artifacts.py
    ├── caches.py
    ├── variables.py
    └── webhooks.py

添加新工具

1. 在 client.py 中添加一个方法
2. 将工具函数添加到相应的 tools/*.py 文件中
3. 就这么简单——无需修改 server.py