CodemagicMcp

Um servidor MCP local em Python que expõe a API REST do Codemagic CI/CD como ferramentas acionáveis pelo Claude.

Documentação

Servidor MCP Codemagic

Um servidor MCP local em Python que expõe a API REST do Codemagic CI/CD como ferramentas chamáveis pelo Claude. Dispare builds, gerencie apps, baixe artefatos e limpe caches — tudo a partir do Claude Code ou Claude Desktop sem sair do chat.

Ferramentas

Apps

Ferramenta	Descrição
`list_apps`	Lista todos os aplicativos na sua conta Codemagic
`get_app`	Obtém detalhes de um aplicativo específico
`add_app`	Adiciona um repositório público ao Codemagic
`add_private_app`	Adiciona um repositório privado usando uma chave SSH
`delete_app` ⚠️	Exclui um aplicativo do Codemagic

Builds

Ferramenta	Descrição
`list_builds`	Lista builds, opcionalmente filtrados por app
`get_build`	Obtém detalhes do build com resumo da contagem de etapas; passe `include_steps=True` para a lista completa de etapas
`trigger_build`	Dispara um novo build para um aplicativo
`cancel_build` ⚠️	Cancela um build em execução
`get_build_logs`	Obtém um resumo passo a passo do status de um build (filtrável por status)
`get_step_logs`	Obtém logs brutos inline ou cria/atualiza um arquivo temporário gerenciado para uma etapa específica do build
`get_step_log_artifact`	Verifica se um artefato de log de etapa local gerenciado ainda existe para uma etapa específica do build
`list_build_artifacts`	Lista todos os artefatos produzidos por um build

Artefatos

Ferramenta	Descrição
`get_artifact_url`	Obtém a URL de download de um artefato de build
`create_artifact_public_url`	Cria uma URL pública com tempo limitado para um artefato

Caches

Ferramenta	Descrição
`list_caches`	Lista todos os caches de build de um aplicativo
`delete_cache` ⚠️	Exclui um cache de build específico
`delete_all_caches` ⚠️	Exclui todos os caches de build de um aplicativo

Variáveis de Ambiente

Ferramenta	Descrição
`list_variables`	Lista todas as variáveis de ambiente de um aplicativo
`add_variable`	Adiciona uma variável de ambiente a um aplicativo
`update_variable`	Atualiza uma variável de ambiente existente
`delete_variable` ⚠️	Exclui uma variável de ambiente

Webhooks

Ferramenta	Descrição
`list_webhooks`	Lista todos os webhooks de um aplicativo
`add_webhook`	Adiciona um webhook a um aplicativo
`delete_webhook` ⚠️	Exclui um webhook

⚠️ Essas ferramentas são marcadas como destrutivas e solicitarão confirmação antes de executar.

Início Rápido

A maneira mais rápida de começar com o Claude Code — sem necessidade de etapa de instalação separada:

# 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

É isso. Veja Configuração para configurações opcionais como CODEMAGIC_DEFAULT_APP_ID.

Instalação

Requisitos: Python 3.11+

Opção 1 — uvx (recomendado, sem instalação necessária)

uvx codemagic-mcp

Opção 2 — pip

pip install codemagic-mcp

Opção 3 — a partir do código-fonte

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

Configuração

Obtenha seu token de API em Configurações do usuário Codemagic → Integrações → API Codemagic.

Você pode fornecer as configurações como variáveis de ambiente ou por meio de um arquivo .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 de App Padrão

CODEMAGIC_DEFAULT_APP_ID é opcional, mas recomendado se você trabalha principalmente com um app. Quando definido, a IA o usará automaticamente sempre que uma ferramenta exigir um app_id e nenhum for especificado. Se não estiver definido, a IA:

Chamará list_apps para descobrir os apps disponíveis.
Usará o app automaticamente se apenas um existir.
Apresentará a lista e pedirá que você escolha se vários apps forem encontrados.

Entrega de Arquivo de Log de Etapa

get_step_logs suporta dois modos de entrega:

delivery="file" é o padrão e grava o log em um arquivo temporário local gerenciado, retornando metadados como artifact_id, file_path, bytes, line_count e expires_at.
delivery="inline" retorna o texto bruto do log da etapa diretamente.

O modo de arquivo local é útil quando um log de etapa é grande demais para ser retornado inline confortavelmente. Os arquivos de log gerenciados são armazenados em CODEMAGIC_LOG_TEMP_DIR e os arquivos expirados são limpos oportunisticamente sempre que um novo arquivo de log é gravado. A janela de retenção padrão é controlada por CODEMAGIC_LOG_TTL_SECONDS e o padrão é 3600 segundos.

O servidor também executa uma limpeza de inicialização e um loop de limpeza em segundo plano periódico. O intervalo do loop é controlado por CODEMAGIC_LOG_CLEANUP_INTERVAL_SECONDS e o padrão é 300 segundos. Como proteção adicional, o diretório temporário gerenciado é limitado por CODEMAGIC_LOG_MAX_TOTAL_BYTES e CODEMAGIC_LOG_MAX_FILE_COUNT; quando qualquer um dos limites é excedido, os arquivos mais antigos são removidos primeiro.

get_step_log_artifact(build_id, step_id) verifica se esse artefato gerenciado ainda existe sem chamar o Codemagic novamente ou retornar o conteúdo do arquivo. Os metadados do artefato incluem um artifact_id determinístico neste formato:

artifact_<build_id>_<step_id>

Se o artefato estiver ausente, o servidor retorna status="missing" com o motivo not_generated_or_expired, o que significa que o arquivo nunca foi gerado ou expirou e foi excluído.

Registrar com o Claude Code

Execute o seguinte comando para adicionar o servidor:

claude mcp add codemagic -- codemagic-mcp

Em seguida, defina sua chave de API na configuração de env do MCP, ou exporte-a no seu shell antes de iniciar o Claude Code:

export CODEMAGIC_API_KEY=your-api-key-here

Alternativamente, adicione manualmente ao ~/.claude.json:

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

Usando uvx (sem instalação prévia necessária)

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

Reinicie o Claude Code — as ferramentas aparecerão em /tools.

Registrar com o Claude Desktop

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %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"
      }
    }
  }
}

Reinicie o Claude Desktop para aplicar as alterações.

Estrutura do Projeto

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

Adicionando Novas Ferramentas

Adicione um método ao client.py
Adicione a função da ferramenta ao arquivo tools/*.py relevante
Pronto — server.py nunca precisa ser alterado