XcodeMCP

Un servidor MCP para controlar Xcode en macOS usando JavaScript for Automation (JXA).

Documentación

Uso con el Xcode MCP oficial de Apple: Apple ahora proporciona un servidor Xcode MCP oficial. XcodeMCP puede ejecutarse junto a él en modo sidekick (--sidekick-only), proporcionando herramientas complementarias como gestión de proyectos y análisis de XCResult. En una versión futura, XcodeMCP pasará al modo solo-sidekick por defecto. Consulta la configuración a continuación.

XcodeMCP

Servidor Model Context Protocol (MCP) que controla Xcode directamente mediante JavaScript for Automation (JXA). Disponible tanto como servidor MCP como CLI independiente.

Qué hace

Controla Xcode directamente mediante JavaScript for Automation (no xcodebuild CLI)
Abre proyectos, compila, ejecuta, prueba y depura desde Xcode
Analiza registros de compilación con ubicaciones de error precisas usando XCLogParser
Proporciona validación integral del entorno y comprobaciones de salud
Admite degradación gradual cuando faltan dependencias opcionales
NUEVO: Incluye un CLI completo con 100% de paridad de funciones con el servidor MCP

Requisitos

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

Uso

XcodeMCP se puede usar de dos maneras:

Servidor MCP: Integración con Claude Desktop, VS Code u otros clientes MCP
Herramienta CLI: Ejecuta comandos directamente desde la terminal con xcodecontrol

Instalación rápida

XCLogParser es recomendado pero opcional:

brew install xclogparser

Instalación desde npm

Ejecuta directamente con npx:

npx -y xcodemcp@latest

O instala globalmente:

npm install -g xcodemcp

Configuración de MCP

Añade a tu configuración de MCP:

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

Configuración de Claude Code CLI

Para añadir XcodeMCP a Claude Code usando la línea de comandos:

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

Sin la herramienta de limpieza de carpeta de compilación

Para añadir XcodeMCP a Claude Code usando la línea de comandos:

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

Uso de valores preferidos para flujos de trabajo de proyecto único

Para proyectos donde trabajas con un único xcodeproj y scheme, puedes configurar valores preferidos para que los parámetros de las herramientas sean opcionales:

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

Con valores preferidos configurados:

Los parámetros de las herramientas pasan a ser opcionales en lugar de obligatorios
Las descripciones de las herramientas muestran valores por defecto (p. ej., "por defecto MyApp.xcodeproj")
Aún puedes anular los valores por defecto proporcionando parámetros explícitos
Reduce la repetición al trabajar con un solo proyecto

Solución de problemas

Si /mcp en Claude Code indica que el MCP falló, intenta ejecutarlo manualmente desde la carpeta del proyecto para ver cuál es la salida: npx -y xcodemcp@latest

Modo sidekick

Al usar XcodeMCP junto con el servidor Xcode MCP oficial de Apple, activa el modo sidekick para incluir solo herramientas complementarias:

Gestión de proyectos: Abrir/cerrar proyectos, gestionar schemes, información del workspace
Análisis de XCResult: Explorar resultados de pruebas, extraer capturas de pantalla, inspeccionar jerarquías de UI

Esto excluye las herramientas de compilación/ejecución/prueba/depuración que el MCP de Apple maneja de forma nativa.

Configuración de Claude Code CLI (ambos servidores)

Primero, activa Xcode Tools en Xcode > Settings > Intelligence > Model Context Protocol.

Luego añade tanto el Xcode MCP de Apple como XcodeMCP en 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"]}'

Configuración JSON (ambos servidores)

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

Dirección futura: En una versión futura, XcodeMCP pasará al modo solo-sidekick por defecto, centrándose exclusivamente en herramientas que complementen el Xcode MCP oficial de Apple en lugar de duplicar funcionalidad.

Configuración de desarrollo

Para desarrollo 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 de CLI

XcodeMCP incluye un potente CLI que ofrece 100% de paridad de funciones con el servidor MCP, permitiéndote ejecutar cualquier herramienta como un comando de una sola ejecución:

Instalación

Instala globalmente para usar el 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

Resolución de rutas

El CLI admite rutas absolutas y relativas por conveniencia:

# 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

Las rutas relativas se resuelven desde tu directorio de trabajo actual, lo que hace que el CLI sea mucho más conveniente al trabajar dentro de directorios de proyecto.

Control de verbosidad

Controla la salida de registro con indicadores de verbosidad:

# 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

Ejemplos 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

Mapeo de nombres de herramientas

Los comandos del CLI usan kebab-case en lugar de guiones bajos:

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

Herramientas disponibles

Gestión de proyectos:

xcode_open_project - Abrir proyectos y workspaces
xcode_get_workspace_info - Obtener estado y detalles del workspace
xcode_get_projects - Listar proyectos en el workspace
xcode_open_file - Abrir archivos con número de línea opcional

Operaciones de compilación:

xcode_build - Compilar con análisis detallado de errores
xcode_clean - Limpiar artefactos de compilación
xcode_test - Ejecutar pruebas con argumentos opcionales
xcode_build_and_run - Compilar y ejecutar el scheme activo
xcode_debug - Iniciar sesión de depuración
xcode_stop - Detener la operación actual

Configuración:

xcode_get_schemes - Listar schemes disponibles
xcode_set_active_scheme - Cambiar el scheme activo
xcode_get_run_destinations - Listar simuladores y dispositivos

Análisis de XCResult:

xcresult_browse - Explorar resultados de pruebas y analizar fallos
xcresult_browser_get_console - Obtener salida de consola para pruebas específicas
xcresult_summary - Resumen rápido de resultados de pruebas
xcresult_get_screenshot - Extraer capturas de pantalla de fallos de pruebas
xcresult_get_ui_hierarchy - Obtener jerarquía de UI como JSON legible por IA con selección de marca de tiempo
xcresult_get_ui_element - Obtener propiedades detalladas de elementos de UI específicos por índice
xcresult_list_attachments - Listar todos los adjuntos de una prueba
xcresult_export_attachment - Exportar adjuntos específicos de resultados de pruebas

Diagnóstico:

xcode_health_check - Validación del entorno y solución de problemas

Funciones de análisis de XCResult

XcodeMCP proporciona herramientas integrales para analizar resultados de pruebas de Xcode (archivos .xcresult), facilitando la depuración de fallos de pruebas y la extracción de información valiosa:

Análisis de resultados de pruebas

Explorar resultados: Navega por jerarquías de pruebas, consulta el estado de aprobado/fallido y examina información detallada de las pruebas
Registros de consola: Extrae la salida de consola y las actividades de prueba con marcas de tiempo precisas para depuración
Resúmenes rápidos: Obtén estadísticas generales, incluyendo tasas de aprobación, recuentos de fallos y duración

Depuración visual

Extracción de capturas de pantalla: Extrae capturas de pantalla PNG de fallos de pruebas usando extracción de fotogramas de ffmpeg desde adjuntos de video
Precisión de marca de tiempo: Especifica marcas de tiempo exactas para capturar el estado de la UI en momentos concretos durante la ejecución de la prueba

Análisis de jerarquía de UI

Formato legible por IA: Extrae jerarquías de UI como JSON comprimido con propiedades de una sola letra (t=tipo, l=etiqueta, f=marco, c=hijos, j=índice)
Selección de marca de tiempo: Encuentra automáticamente la captura de jerarquía de UI más cercana a cualquier marca de tiempo especificada
Análisis profundo de elementos: Usa referencias de índice para obtener detalles completos de cualquier elemento de UI, incluyendo propiedades de accesibilidad e información de marco
Optimización de tamaño: Reducción de tamaño del 75%+ en comparación con los datos completos de jerarquía, manteniendo toda la información esencial

Gestión de adjuntos

Inventario completo: Lista todos los adjuntos (capturas de pantalla, videos, descripciones de depuración, jerarquías de UI) de cualquier prueba
Exportación selectiva: Exporta adjuntos específicos por índice o tipo
Detección inteligente: Identifica y categoriza automáticamente diferentes tipos de adjuntos

Ejemplos 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

Configuración

Configuración de registro

XcodeMCP admite registro configurable para ayudar con la depuración y el monitoreo:

Variables de entorno

LOG_LEVEL: Controla la verbosidad del registro (por defecto: INFO)
- SILENT: Sin salida de registro
- ERROR: Solo mensajes de error
- WARN: Advertencias y errores
- INFO: Información operativa general (recomendado)
- DEBUG: Información de diagnóstico detallada
XCODEMCP_LOG_FILE: Ruta de archivo opcional para el registro
- Los registros se escriben en el archivo especificado además de stderr
- Los directorios principales se crean automáticamente
- Ejemplo: /tmp/xcodemcp.log o ~/Library/Logs/xcodemcp.log
XCODEMCP_CONSOLE_LOGGING: Activar/desactivar salida de consola (por defecto: true)
- Establece false para desactivar el registro de stderr (útil cuando se usa solo registro de archivo)

Ejemplos

Registro de depuración con salida de archivo:

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

Modo silencioso (sin registro):

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

Registro solo de archivo:

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

Todos los registros están correctamente formateados con marcas de tiempo y niveles de registro, y la salida de stderr mantiene compatibilidad con el protocolo MCP.

Solución de problemas

XCLogParser no encontrado

Si ves una advertencia de que XCLogParser no se encuentra aunque esté instalado:

Verifica la instalación:
```
which xclogparser
xclogparser version
```
Problemas comunes y soluciones:
- Problema de PATH: Si which xclogparser no devuelve nada, añade el directorio de instalación a tu 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 incorrecto: La documentación anterior puede hacer referencia a xclogparser --version, pero el comando correcto es xclogparser version (sin guiones)
- Problema de permisos: Asegúrate de que xclogparser sea ejecutable:
```
chmod +x $(which xclogparser)
```

Validación del entorno: Ejecuta la comprobación de salud para obtener diagnósticos detallados:

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

Nota: XcodeMCP puede funcionar sin XCLogParser, pero el análisis de errores de compilación será limitado.

Ejemplo de salida

Compilación con errores:

❌ 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'

Comprobación de salud:

✅ 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