XcodeBuild MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Compile e teste qualquer projeto ou workspace do Xcode (schemes, configurações, destinos)
Inicie simuladores, instale apps, lance, envie URLs, digite texto, toque em coordenadas
Capture screenshots e logs do sistema/app por execução
Suporte ao Swift Package Manager junto com .xcodeproj
Descobre projetos em um diretório para minimizar digitação de caminho nos prompts

Demo ao vivo

Como fica na prática

xcodebuild.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "xcodebuild": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "xcodebuild",
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "xcodebuild": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "xcodebuildmcp@latest"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add xcodebuild -- npx -y xcodebuildmcp@latest

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: XcodeBuild

Verifique que o código iOS gerado por AI realmente compila e executa no simulador

👤 Devs iOS usando Claude para trabalho em features, prototipagem SwiftUI ⏱ ~15 min intermediate

Quando usar: Claude acabou de escrever ou editar views SwiftUI. Antes de dizer 'pronto', você quer compilar, executar no simulador, e tirar um screenshot.

Pré-requisitos

Xcode instalado — Xcode 15+ da Mac App Store; confirme com xcodebuild -version
Um simulador inicializável — Xcode → Configurações → Plataformas → iOS Simulator baixado

Fluxo

Descubra o projeto e compile

Encontre o projeto Xcode em /Users/me/Projects/MyApp. Compile scheme 'MyApp' para destino iOS Simulator 'iPhone 16'. Relate quaisquer erros ou avisos.✓ Copiado

→ Compilação bem-sucedida, ou erros específicos com arquivo:linha
Inicie simulador, instale, lance

Inicie um simulador iPhone 16 se ainda não estiver iniciado. Instale o app compilado e lance. Tire um screenshot depois de 3 segundos.✓ Copiado

→ App em execução; screenshot capturado
Conduza a feature

Toque no botão 'Sign Up', digite '[email protected]' no campo de email, toque Enviar. Screenshot depois de cada passo.✓ Copiado

→ Sequência de screenshots mostrando o fluxo; ou um erro claro de tap falho

Resultado: Screenshots antes/depois que provam que a feature funciona, commitados junto com o código.

Armadilhas

Tocar por coordenada é frágil entre tamanhos de dispositivo — Prefira taps baseados em label de acessibilidade quando o MCP os suportar; use coordenadas apenas como fallback
Compilação de simulador usa uma arquitetura diferente de um dispositivo real — Para código sensível à arquitetura, também compile para um dispositivo físico pelo menos uma vez antes de fazer merge

Combine com: filesystem · github

Execute seus testes unitários e UI do Xcode do chat e faça triagem de falhas

👤 Devs iOS que querem feedback rápido de testes sem mudar para Xcode ⏱ ~10 min beginner

Quando usar: Você fez uma mudança, quer executar equivalente a ⌘U, e ter Claude fazer parse de falhas.

Fluxo

Execute testes

Execute todos os testes para scheme 'MyApp' no destino 'iPhone 16'. Mostre-me quaisquer falhas com arquivo, linha, e expectativa.✓ Copiado

→ Contagem de passes mais lista de falhas com localizações
Foque em uma falha

Para a primeira falha, leia o arquivo de fonte e diga-me se o teste está errado ou o código está errado. Seja específico.✓ Copiado

→ Diagnóstico claro, não 'poderia ser um ou outro'
Corrija e reexecute

Aplique a correção. Reexecute apenas o teste que falha para confirmar verde.✓ Copiado

→ Reexecução verde

Resultado: Testes de volta ao verde com uma reexecução focada, não uma reexecução de suite inteira.

Armadilhas

xcodebuild test é lento em caches frios — Use flag -only-testing: para estreitar; o MCP expõe isso via test-by-identifier

Combine com: github

Diagnostique um erro de compilação Xcode críptico

👤 Devs iOS que batem em uma parede de 'erro de linker / framework ausente / assinatura' ⏱ ~20 min intermediate

Quando usar: xcodebuild falha e a saída de erro são 4000 linhas de ruído.

Fluxo

Compile e capture a falha bruta

Compile scheme 'MyApp' e retorne apenas as linhas contendo 'error:' ou 'warning:', mais 3 linhas de contexto ao redor de cada uma.✓ Copiado

→ Lista de erro focada sem ruído
Explique o primeiro erro

Explique o primeiro erro em termos humanos. Sobre o que Xcode realmente está reclamando, e quais são as 3 principais causas?✓ Copiado

→ Diagnóstico em inglês simples com causas prováveis
Aplique correção e reconstrua

Aplique a correção mais provável (verifique Info.plist/entitlements/Package.swift conforme necessário), reconstrua, e confirme que o erro se foi.✓ Copiado

→ Compilação limpa

Resultado: Destrancado da parede de compilação sem um buraco de coelho Stack Overflow de 2 horas.

Armadilhas

Alguns erros são staleness DerivedData — Quando tudo mais falhar: limpe DerivedData via ferramenta clean do MCP, depois reconstrua

Combine com: filesystem

Capture um crash de app no simulador e encontre a causa raiz

👤 Devs iOS caçando um crash reproduzível ⏱ ~20 min advanced

Quando usar: Seu app crasha em um fluxo específico no simulador, e você quer Claude ler o log de crash.

Fluxo

Reproduza com captura de log

Lance MyApp no simulador iPhone 16. Inicie captura de log. Execute este fluxo: abra Configurações, toque em 'Limpar Cache'. Pare captura de log quando o app morre.✓ Copiado

→ Crash reproduzido, logs salvos
Analise o crash

Encontre o crash nos logs capturados. Simbolize se necessário. Diga-me a thread que falha, os 5 principais stack frames, e a linha provável em nosso código.✓ Copiado

→ Stack trace simbolizado apontando para um arquivo de fonte específico
Proponha a correção

Com base no stack trace e no código circundante, qual é a mudança mínima para corrigi-la? Aplique.✓ Copiado

→ Correção direcionada, não um grande refactor

Resultado: Um crash corrigido com evidência simbolizada que você pode colar no PR.

Armadilhas

Crashes de configuração Release não simbolizam sem dSYMs — Use configuração Debug para repro; teste separadamente Release para confirmar correção

Combine com: sentry · github

Combinações

Combine com outros MCPs para 10× de alavancagem

xcodebuild + filesystem

Edite Swift → compile → screenshot → iterate, inteiramente em um chat

Edite ContentView.swift para adicionar um toggle dark-mode. Compile MyApp para iPhone 16, execute, tire um screenshot em ambos os modos light e dark.✓ Copiado

xcodebuild + github

Corrija um problema, verifique no simulador, abra PR com um screenshot

Issue #42 diz que o botão de login está desalinhado em paisagem. Reproduza no simulador iPad, corrija o layout SwiftUI, anexe screenshots antes/depois ao PR.✓ Copiado

xcodebuild + sentry

Reproduza um crash reportado por Sentry no simulador com condições idênticas

Crash Sentry iOS-113 aconteceu no iOS 18.1 com locale de usuário fr-FR. Inicie um simulador correspondente, reproduza, e corrija.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
discover_projects	directory: str	Encontre o que compilar em um repo sem digitação de caminho	free
build_project	project: str, scheme: str, destination: str, configuration?: 'Debug'\|'Release'	Compile um .xcodeproj ou .xcworkspace para um destino	free
build_spm_package	path: str	Compile um Swift Package (sem .xcodeproj)	free
test_project	project, scheme, destination, only_testing?: str[]	Execute a suite de testes; use only_testing para estreitar	free
list_simulators	none	Veja quais simuladores existem e quais estão inicializados	free
boot_simulator	simulator_id or name: str	Traga um simulador para cima antes de instalar apps	free
install_app	simulator_id: str, app_path: str	Instale o .app compilado em um simulador inicializado	free
launch_app	simulator_id: str, bundle_id: str	Inicie o app instalado	free
tap_at / type_text / send_url	simulator params	Conduza a UI	free
screenshot	simulator_id: str, path?: str	Capture estado visual	free
start_log_capture / stop_log_capture	simulator_id	Capture logs de console/sistema para uma sessão	free
clean	project, scheme?	Limpe DerivedData para esse projeto quando compilações ficam estranhas	free

Custo e limites

O que custa rodar

Cota de API: Nenhum — tudo executa localmente via xcodebuild/simctl
Tokens por chamada: Logs de compilação podem ser enormes. Prefira filtrar para erros/avisos em vez de despejos de log completos
Monetário: Gratuito (requer um Mac com Xcode, que tem seu próprio custo)
Dica: Execute compilações incrementais, não compilações limpas, por padrão. Limpe apenas quando DerivedData fica estranho.

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Sem credenciais no layer MCP. Credenciais de assinatura de código vivem no Keychain do seu Mac como usual.

Saída de dados: Nenhum do MCP. xcodebuild pode buscar dependências (SPM, CocoaPods) de suas fontes usuais.

Nunca conceda: não deixe o agente alterar identidades de codesign ou perfis de provisionamento sem confirmação

Compilações de simulador diferem de compilações de dispositivo. Sempre teste em um dispositivo real antes de lançar.
O MCP pode executar scripts de compilação Xcode (fases Run Script) que podem fazer qualquer coisa — trate qualquer projeto não confiável como trataria código não confiável.

Solução de problemas

Erros comuns e correções

xcodebuild: command not found

Xcode Command Line Tools ausentes ou não selecionadas. Execute xcode-select --install depois sudo xcode-select -s /Applications/Xcode.app/Contents/Developer.

Verificar: xcodebuild -version

No such destination 'iPhone 16'

Simulador com esse nome não está baixado para o Xcode ativo. Abra Xcode → Configurações → Plataformas → baixe iOS runtime. Ou use list_simulators e escolha um existente.

Verificar: xcrun simctl list devices

Build succeeds but app won't launch — 'NSException'

Verifique logs do app via start_log_capture logo antes de lançar. Frequentemente Info.plist com chave ausente, ou entitlements desalinhado.

Tests hang on a SwiftUI preview

Previsualizações SwiftUI podem deadlock xcodebuild test em casos raros. Desabilite preview helpers em schemes de teste, ou execute com -disable-concurrent-testing.

Alternativas

XcodeBuild vs. outros

Alternativa	Quando usar	Troca
Direct shell MCP running xcodebuild	Você quer máxima flexibilidade e aceita o tradeoff de segurança de um shell MCP bruto	Sem ergonomia; Claude tem que conhecer cada flag xcodebuild
JetBrains MCP (AppCode is EOL)	Você está em JetBrains IDE — não se aplica mais a iOS	Não é uma alternativa iOS hoje
Fastlane via shell	Você precisa de compilações assinadas e uploads TestFlight, não apenas verificação de simulador	Muito mais pesado; fora do escopo para dev de inner-loop

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills