XcodeMCP

Usando com o Xcode MCP oficial da Apple: A Apple agora fornece um servidor Xcode MCP oficial. O XcodeMCP pode ser executado junto com ele no modo sidekick (--sidekick-only), fornecendo ferramentas complementares como gerenciamento de projetos e análise de XCResult. Em uma versão futura, o XcodeMCP fará a transição para o modo somente-sidekick por padrão. Veja a configuração abaixo.

XcodeMCP

Servidor Model Context Protocol (MCP) que controla o Xcode diretamente por meio de JavaScript for Automation (JXA). Disponível tanto como servidor MCP quanto como CLI autônomo.

O que ele faz

• Controla o Xcode diretamente por meio de JavaScript for Automation (não pela CLI do xcodebuild)
• Abre projetos, compila, executa, testa e depura dentro do Xcode
• Analisa logs de build com localizações precisas de erros usando XCLogParser
• Fornece validação abrangente do ambiente e verificações de integridade
• Suporta degradação graciosa quando dependências opcionais estão ausentes
• NOVO: Inclui uma CLI completa com 100% de paridade de recursos com o servidor MCP

Requisitos

• macOS com Xcode instalado
• Node.js 18+
• XCLogParser (recomendado): brew install xclogparser

Uso

O XcodeMCP pode ser usado de duas maneiras:

1. Servidor MCP: Integre com Claude Desktop, VS Code ou outros clientes MCP
2. Ferramenta CLI: Execute comandos diretamente do terminal com xcodecontrol

Instalação Rápida

O XCLogParser é recomendado, mas opcional:

brew install xclogparser

Instalar a partir do npm

Execute diretamente com npx:

npx -y xcodemcp@latest

Ou instale globalmente:

npm install -g xcodemcp

Configuração do MCP

Adicione à sua configuração do MCP:

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
      }
    }
  }
}

Configuração da CLI do Claude Code

Para adicionar o XcodeMCP ao Claude Code usando a linha de comando:

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
  }
}'

Sem a ferramenta de limpeza da pasta de build

Para adicionar o XcodeMCP ao Claude Code usando a linha de comando:

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest", "--no-clean"],
  "env": {
  }
}'

Usando Valores Preferidos para Fluxos de Trabalho de Projeto Único

Para projetos em que você trabalha com um único xcodeproj e scheme, você pode configurar valores preferidos para tornar os parâmetros das ferramentas opcionais:

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
    "XCODE_MCP_PREFERRED_SCHEME": "MyApp",
    "XCODE_MCP_PREFERRED_XCODEPROJ": "MyApp.xcodeproj"
  }
}'

Com valores preferidos configurados:

• Os parâmetros das ferramentas tornam-se opcionais em vez de obrigatórios
• As descrições das ferramentas mostram valores padrão (por exemplo, "padrão para MyApp.xcodeproj")
• Você ainda pode substituir os padrões fornecendo parâmetros explícitos
• Reduz a repetição ao trabalhar com um único projeto

Solução de Problemas

Se /mcp no Claude Code indicar que o MCP falhou, tente executá-lo manualmente a partir da pasta do projeto para ver qual é a saída: npx -y xcodemcp@latest

Modo Sidekick

Ao usar o XcodeMCP junto com o servidor Xcode MCP oficial da Apple, ative o modo sidekick para incluir apenas ferramentas complementares:

• Gerenciamento de projetos: Abrir/fechar projetos, gerenciar schemes, informações do workspace
• Análise de XCResult: Navegar pelos resultados de testes, extrair capturas de tela, inspecionar hierarquias de UI

Isso exclui as ferramentas de compilar/executar/testar/depurar que o MCP da Apple trata nativamente.

Configuração da CLI do Claude Code (Ambos os Servidores)

Primeiro, ative o Xcode Tools em Xcode > Configurações > Inteligência > Model Context Protocol.

Em seguida, adicione tanto o Xcode MCP da Apple quanto o XcodeMCP no modo sidekick:

# Add Apple's official Xcode MCP
claude mcp add --transport stdio xcode -- xcrun mcpbridge

# Add XcodeMCP in sidekick mode (project management + XCResult analysis)
claude mcp add-json xcodemcp '{"command": "npx", "args": ["-y", "xcodemcp@latest", "--sidekick-only"]}'

Configuração JSON (Ambos os Servidores)

{
  "mcpServers": {
    "xcode": {
      "command": "xcrun",
      "args": ["mcpbridge"]
    },
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest", "--sidekick-only"]
    }
  }
}

Direção futura: Em uma versão futura, o XcodeMCP fará a transição para o modo somente-sidekick por padrão, focando exclusivamente em ferramentas que complementam o Xcode MCP oficial da Apple, em vez de duplicar funcionalidades.

Configuração de Desenvolvimento

Para desenvolvimento local:

git clone https://github.com/lapfelix/XcodeMCP.git
cd XcodeMCP
npm install

# Run in development mode (TypeScript)
npm run dev:ts

# Or build and run compiled version
npm run build
npm start

Uso da CLI

O XcodeMCP inclui uma CLI poderosa que fornece 100% de paridade de recursos com o servidor MCP, permitindo que você execute qualquer ferramenta como um comando único:

Instalação

Instale globalmente para usar a CLI:

npm install -g xcodemcp

Uso Básico

# Show help and available tools
xcodecontrol --help

# Run a tool with flags  
xcodecontrol build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

# Get help for a specific tool
xcodecontrol build --help

# Use JSON input instead of flags
xcodecontrol build --json-input '{"xcodeproj": "/path/to/Project.xcodeproj", "scheme": "MyScheme"}'

# Output results in JSON format
xcodecontrol --json health-check

Resolução de Caminhos

A CLI suporta caminhos absolutos e relativos por conveniência:

# Absolute paths (traditional)
xcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# Relative paths (NEW in v2.0.0)
xcodecontrol build --xcodeproj MyApp.xcodeproj --scheme MyApp
xcodecontrol build --xcodeproj ../OtherProject/OtherProject.xcodeproj --scheme OtherApp

# Works with file paths too
xcodecontrol open-file --filePath src/ViewController.swift --lineNumber 42

Caminhos relativos são resolvidos a partir do seu diretório de trabalho atual, tornando a CLI muito mais conveniente de usar ao trabalhar dentro de diretórios de projeto.

Controle de Verbosidade

Controle a saída de logs com sinalizadores de verbosidade:

# Verbose mode (shows INFO and DEBUG logs)
xcodecontrol -v build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

# Quiet mode (only errors)
xcodecontrol -q test --xcodeproj /path/to/Project.xcodeproj

# Default mode (warnings and errors only)
xcodecontrol run --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

Exemplos Rápidos

# Check system health
xcodecontrol health-check

# Build a project
xcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# Run the app
xcodecontrol run --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# Run tests
xcodecontrol test --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj

# Clean build directory
xcodecontrol clean --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj

# Browse XCResult files
xcodecontrol xcresult-browse --xcresult-path /path/to/result.xcresult

# Get UI hierarchy from test failure
xcodecontrol xcresult-get-ui-hierarchy --xcresult-path /path/to/result.xcresult --test-id "MyTest/testMethod()" --timestamp 30.5

Mapeamento de Nomes de Ferramentas

Os comandos da CLI usam kebab-case em vez de underscores:

• xcode_build → build
• xcode_test → test
• xcode_build_and_run → build-and-run
• xcode_health_check → health-check
• xcresult_browse → xcresult-browse
• find_xcresults → find-xcresults

Ferramentas Disponíveis

Gerenciamento de Projetos:

• xcode_open_project - Abrir projetos e workspaces
• xcode_get_workspace_info - Obter status e detalhes do workspace
• xcode_get_projects - Listar projetos no workspace
• xcode_open_file - Abrir arquivos com número de linha opcional

Operações de Build:

• xcode_build - Compilar com análise detalhada de erros
• xcode_clean - Limpar artefatos de build
• xcode_test - Executar testes com argumentos opcionais
• xcode_build_and_run - Compilar e executar o scheme ativo
• xcode_debug - Iniciar sessão de depuração
• xcode_stop - Parar operação atual

Configuração:

• xcode_get_schemes - Listar schemes disponíveis
• xcode_set_active_scheme - Alternar scheme ativo
• xcode_get_run_destinations - Listar simuladores e dispositivos

Análise de XCResult:

• xcresult_browse - Navegar pelos resultados de testes e analisar falhas
• xcresult_browser_get_console - Obter saída do console para testes específicos
• xcresult_summary - Visão geral rápida dos resultados de testes
• xcresult_get_screenshot - Extrair capturas de tela de falhas de testes
• xcresult_get_ui_hierarchy - Obter hierarquia de UI como JSON legível por IA com seleção de timestamp
• xcresult_get_ui_element - Obter propriedades detalhadas de elementos de UI específicos por índice
• xcresult_list_attachments - Listar todos os anexos de um teste
• xcresult_export_attachment - Exportar anexos específicos dos resultados de testes

Diagnóstico:

• xcode_health_check - Validação do ambiente e solução de problemas

Recursos de Análise de XCResult

O XcodeMCP fornece ferramentas abrangentes para analisar resultados de testes do Xcode (arquivos .xcresult), facilitando a depuração de falhas de testes e a extração de informações valiosas:

Análise de Resultados de Testes

• Navegar pelos Resultados: Percorra hierarquias de testes, visualize status de aprovação/reprovação e examine informações detalhadas de testes
• Logs do Console: Extraia saída do console e atividades de testes com timestamps precisos para depuração
• Resumos Rápidos: Obtenha estatísticas gerais, incluindo taxas de aprovação, contagens de falhas e duração

Depuração Visual

• Extração de Capturas de Tela: Extraia capturas de tela PNG de falhas de testes usando extração de quadros do ffmpeg a partir de anexos de vídeo
• Precisão de Timestamp: Especifique timestamps exatos para capturar o estado da UI em momentos específicos durante a execução dos testes

Análise de Hierarquia de UI

• Formato Legível por IA: Extraia hierarquias de UI como JSON compactado com propriedades de letra única (t=tipo, l=rótulo, f=quadro, c=filhos, j=índice)
• Seleção de Timestamp: Encontre automaticamente a captura de hierarquia de UI mais próxima de qualquer timestamp especificado
• Mergulho em Elementos: Use referências de índice para obter detalhes completos de qualquer elemento de UI, incluindo propriedades de acessibilidade e informações de quadro
• Otimização de Tamanho: Redução de 75%+ no tamanho em comparação com dados completos de hierarquia, mantendo todas as informações essenciais

Gerenciamento de Anexos

• Inventário Completo: Liste todos os anexos (capturas de tela, vídeos, descrições de depuração, hierarquias de UI) de qualquer teste
• Exportação Seletiva: Exporte anexos específicos por índice ou tipo
• Detecção Inteligente: Identifique e categorize automaticamente diferentes tipos de anexos

Exemplos de Uso

# Browse test results
xcresult_browse "/path/to/TestResults.xcresult"

# Get console output to find failure timestamps
xcresult_browser_get_console "/path/to/TestResults.xcresult" "MyTest/testMethod()"

# Get UI hierarchy at specific timestamp (AI-readable slim version)
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25

# Get full UI hierarchy (with size warning)
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25 true

# Get detailed properties of a specific UI element
xcresult_get_ui_element "/path/to/ui_hierarchy_full.json" 15

# Extract screenshot at failure point
xcresult_get_screenshot "/path/to/TestResults.xcresult" "MyTest/testMethod()" 30.71

Configuração

Configuração de Logging

O XcodeMCP suporta logging configurável para ajudar na depuração e monitoramento:

Variáveis de Ambiente

• LOG_LEVEL: Controla a verbosidade do logging (padrão: INFO)

  • SILENT: Nenhuma saída de log
  • ERROR: Apenas mensagens de erro
  • WARN: Avisos e erros
  • INFO: Informações operacionais gerais (recomendado)
  • DEBUG: Informações detalhadas de diagnóstico

• XCODEMCP_LOG_FILE: Caminho de arquivo opcional para logging

  • Os logs são gravados no arquivo especificado além do stderr
  • Os diretórios pai são criados automaticamente
  • Exemplo: /tmp/xcodemcp.log ou ~/Library/Logs/xcodemcp.log

• XCODEMCP_CONSOLE_LOGGING: Ativar/desativar saída do console (padrão: true)

  • Defina como false para desativar o logging no stderr (útil ao usar apenas logging em arquivo)

Exemplos

Logging de depuração com saída em arquivo:

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "XCODEMCP_LOG_FILE": "~/Library/Logs/xcodemcp.log"
      }
    }
  }
}

Modo silencioso (sem logging):

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx", 
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "SILENT"
      }
    }
  }
}

Logging apenas em arquivo:

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"], 
      "env": {
        "LOG_LEVEL": "INFO",
        "XCODEMCP_LOG_FILE": "/tmp/xcodemcp.log",
        "XCODEMCP_CONSOLE_LOGGING": "false"
      }
    }
  }
}

Todos os logs são formatados adequadamente com timestamps e níveis de log, e a saída do stderr mantém compatibilidade com o protocolo MCP.

Solução de Problemas

XCLogParser Não Encontrado

Se você vir um aviso de que o XCLogParser não foi encontrado, mesmo estando instalado:

1. Verifique a instalação:

   which xclogparser
   xclogparser version
   

2. Problemas comuns e soluções:

   • Problema de PATH: Se which xclogparser não retornar nada, adicione o diretório de instalação ao seu PATH:

     # For Homebrew on Intel Macs
     export PATH="/usr/local/bin:$PATH"
     
     # For Homebrew on Apple Silicon Macs
     export PATH="/opt/homebrew/bin:$PATH"
     

   • Comando errado: Documentação mais antiga pode referenciar xclogparser --version, mas o comando correto é xclogparser version (sem hífens)

   • Problema de permissão: Garanta que o xclogparser seja executável:

     chmod +x $(which xclogparser)
     

3. Validação do ambiente: Execute a verificação de integridade para obter diagnósticos detalhados:

   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "xcode_health_check", "arguments": {}}}' | npx xcodemcp
   

Nota: O XcodeMCP pode operar sem o XCLogParser, mas a análise de erros de build será limitada.

Exemplo de Saída

Build com erros:

❌ BUILD FAILED (2 errors)

ERRORS:
  • /path/HandsDownApp.swift:7:18: Expected 'func' keyword in instance method declaration
  • /path/MenuBarManager.swift:98:13: Invalid redeclaration of 'toggleItem'

Verificação de integridade:

✅ All systems operational

✅ OS: macOS environment detected
✅ XCODE: Xcode found at /Applications/Xcode.app (version 16.4)
✅ XCLOGPARSER: XCLogParser found (XCLogParser 0.2.41)
✅ OSASCRIPT: JavaScript for Automation (JXA) is available
✅ PERMISSIONS: Xcode automation permissions are working