XcodeProj MCP Server

xcodeproj-mcp-server

Un servidor de Model Context Protocol (MCP) para manipular archivos de proyecto de Xcode (.xcodeproj) usando Swift.

Descripción general

xcodeproj-mcp-server es un servidor MCP que proporciona herramientas para manipular programáticamente archivos de proyecto de Xcode. Aprovecha la biblioteca tuist/xcodeproj para una manipulación fiable de archivos de proyecto e implementa el Model Context Protocol usando el swift-sdk.

Este servidor permite a los asistentes de IA y otros clientes MCP:

• Crear nuevos proyectos de Xcode
• Gestionar targets, archivos y configuraciones de compilación
• Inspeccionar la estructura del proyecto, incluidos grupos y jerarquías
• Modificar ajustes de compilación
• Añadir dependencias y frameworks
• Automatizar tareas comunes de proyectos de Xcode

Casos de uso

Creación y configuración de proyectos

• Crear proyectos desde cero: Generar nuevos proyectos de Xcode con configuraciones personalizadas, identificadores de bundle y ajustes de organización sin abrir Xcode
• Andamiaje de proyectos multi-target: Configurar proyectos complejos con múltiples apps, frameworks, tests y extensiones en un único flujo de trabajo automatizado

Automatización del flujo de trabajo de desarrollo

• Añadir nuevos archivos a targets: Después de crear un nuevo archivo Swift, añadirlo automáticamente a los archivos fuente del target correspondiente para su compilación
• Añadir referencias de carpetas: Incluir carpetas de recursos externos o directorios de assets como referencias de carpetas sincronizadas en tu proyecto, reflejando automáticamente cualquier cambio en el sistema de archivos
• Añadir fases de compilación: Integrar formateadores de código, linters o scripts de compilación personalizados en tus targets (p. ej., fases de ejecución de SwiftLint, SwiftFormat)
• Crear frameworks y extensiones de app: Crear rápidamente nuevos targets de framework o extensiones de app para modularizar tu base de código
• Añadir Widget Extensions: Crear e incrustar automáticamente targets de Widget Extension con la configuración adecuada para widgets de la pantalla de inicio de iOS

Gestión de configuración del proyecto

• Automatizar la configuración de Info.plist: Configurar programáticamente los ajustes de Info.plist, entitlements y perfiles de aprovisionamiento para diferentes targets
• Gestión de configuraciones de compilación: Configurar diferentes configuraciones de compilación con flags de compilador, identificadores de bundle y deployment targets adecuados
• Gestión de dependencias: Añadir frameworks del sistema, enlazar bibliotecas y configurar dependencias de targets sin navegación manual en Xcode

Cómo configurarlo para Claude Desktop y Claude Code

Requisitos previos

• macOS (para ejecutar proyectos de Xcode)
• Un runtime de contenedores: container de Apple (recomendado) o Docker

El servidor se distribuye como una imagen de contenedor linux/arm64, que se ejecuta en cualquiera de los dos runtimes.

Configuración con container de Apple (recomendado)

container es la herramienta propia de Apple para ejecutar contenedores Linux como máquinas virtuales ligeras en macOS. Es el runtime recomendado para este servidor: proviene de Apple, no requiere aplicaciones de escritorio de terceros y ejecuta la imagen linux/arm64 publicada de forma nativa en Apple silicon.

Requisitos

• Un Mac con Apple silicon
• macOS 26 o posterior (container no admite versiones anteriores)

Instalación

Instala la CLI de container desde la página oficial de lanzamientos.

container necesita que su servicio en segundo plano esté en ejecución. Inícialo una vez después de instalar y de nuevo después de cada reinicio:

container system start

Luego descarga la imagen precompilada desde GitHub Container Registry:

container image pull ghcr.io/giginet/xcodeproj-mcp-server:latest

container run no tiene opción --pull, así que ejecuta container image pull de nuevo cada vez que quieras actualizar a la última imagen.

Configuración para Claude Code

claude mcp add xcodeproj -- container run --rm -i -v '${CLAUDE_PROJECT_DIR:-.}:/workspace' ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

Esto monta el directorio del proyecto en /workspace dentro del contenedor, que es como el servidor obtiene acceso a tus proyectos de Xcode. Mantén las comillas simples: evitan que tu shell expanda el montaje en el momento del registro, de modo que Claude Code lo resuelve cada vez que inicia el servidor en lugar de fijarlo al directorio desde el que ejecutaste claude mcp add. Se recurre a ., el directorio de trabajo en el que Claude Code inicia el servidor, que es la raíz del proyecto.

Configuración para Claude Desktop

Añade lo siguiente a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "xcodeproj": {
      "command": "/usr/local/bin/container",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${workspaceFolder}:/workspace",
        "ghcr.io/giginet/xcodeproj-mcp-server",
        "/workspace"
      ]
    }
  }
}

El instalador coloca el binario en /usr/local/bin/container. Aquí se usa la ruta absoluta porque ese directorio no siempre está en el PATH de las aplicaciones GUI.

Compilando la imagen localmente

container build lee el mismo Dockerfile:

container build -t xcodeproj-mcp-server:local .

El contenedor de compilación usa por defecto 2 CPUs y 2 GB de memoria. Asígnale más para acelerar la compilación de release:

container build -c 8 -m 8g -t xcodeproj-mcp-server:local .

Configuración con Docker

Usa Docker si estás en macOS 15 o anterior, o si Docker ya forma parte de tu flujo de trabajo.

Descarga la imagen Docker precompilada desde GitHub Container Registry:

docker pull ghcr.io/giginet/xcodeproj-mcp-server

Configuración para Claude Code

claude mcp add xcodeproj -- docker run --pull=always --rm -i -v '${CLAUDE_PROJECT_DIR:-.}:/workspace' ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

Al igual que con container, el directorio del proyecto se monta en /workspace dentro del contenedor para que el servidor pueda acceder a tus proyectos de Xcode, y las comillas simples mantienen el montaje sin expandir hasta que Claude Code inicia el servidor.

Configuración para Claude Desktop

Añade lo siguiente a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "xcodeproj": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${workspaceFolder}:/workspace",
        "ghcr.io/giginet/xcodeproj-mcp-server",
        "/workspace"
      ]
    }
  }
}

Usando el servidor desde Claude Code o Codex dentro de Xcode

Xcode puede ejecutar Claude Code y Codex como agentes de codificación, y lee su configuración de subcarpetas específicas de agentes dentro de ~/Library/Developer/Xcode/CodingAssistant, una carpeta que Xcode usa exclusivamente. La configuración colocada allí solo afecta a los agentes cuando los lanzas en Xcode, por lo que no interfiere con tu configuración habitual de ~/.claude o ~/.codex. Consulta Extending and customizing agents de Apple para más detalles.

Dos cosas difieren de la configuración de línea de comandos:

• Xcode inicia el servidor MCP con el directorio del proyecto como su directorio de trabajo, así que monta . directamente. Codex no tiene equivalente a la expansión ${CLAUDE_PROJECT_DIR:-.} de Claude Code, por lo que esto mantiene a ambos agentes en el mismo montaje.
• Dale a command una ruta absoluta, porque el entorno del agente no necesariamente tiene /usr/local/bin en su PATH.

Claude Code en Xcode

~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig actúa como directorio de configuración de Claude Code. Apunta CLAUDE_CONFIG_DIR a él y usa claude mcp add:

CLAUDE_CONFIG_DIR=~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig \
  claude mcp add xcodeproj -s user -- \
  /usr/local/bin/container run --rm -i -v .:/workspace ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

Eso escribe el servidor en ClaudeAgentConfig/.claude.json. Para añadirlo manualmente, añade una entrada bajo mcpServers:

{
  "mcpServers": {
    "xcodeproj": {
      "type": "stdio",
      "command": "/usr/local/bin/container",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        ".:/workspace",
        "ghcr.io/giginet/xcodeproj-mcp-server:latest",
        "/workspace"
      ]
    }
  }
}

Codex en Xcode

~/Library/Developer/Xcode/CodingAssistant/codex actúa como CODEX_HOME de Codex:

CODEX_HOME=~/Library/Developer/Xcode/CodingAssistant/codex \
  codex mcp add xcodeproj -- \
  /usr/local/bin/container run --rm -i -v .:/workspace ghcr.io/giginet/xcodeproj-mcp-server:latest /workspace

Eso escribe el servidor en codex/config.toml. Para añadirlo manualmente:

[mcp_servers.xcodeproj]
command = "/usr/local/bin/container"
args = ["run", "--rm", "-i", "-v", ".:/workspace", "ghcr.io/giginet/xcodeproj-mcp-server:latest", "/workspace"]

Si configuraste con Docker, usa la ruta absoluta a tu binario docker en lugar de /usr/local/bin/container. Reinicia el agente en Xcode después de cambiar su configuración.

Ajustes recomendados para Claude Code

Habilitar ENABLE_TOOL_SEARCH en .claude/settings.json activa la carga dinámica de herramientas MCP. Esto evita que las herramientas MCP no utilizadas consuman contexto.

{
  "env": {
    "ENABLE_TOOL_SEARCH": "1"
  }
}

Seguridad de rutas

El servidor MCP ahora admite restringir las operaciones de archivos a un directorio base específico. Cuando proporcionas una ruta base como argumento de línea de comandos:

• Todos los parámetros project_path y de rutas de archivos se resolverán en relación con esta ruta base
• Las rutas absolutas se validan para asegurar que están dentro del directorio base
• Cualquier intento de acceder a archivos fuera del directorio base resultará en un error

Esto es especialmente útil cuando se ejecuta el servidor en contenedores u otros entornos de sandbox.

Herramientas disponibles

Gestión de proyectos

• create_xcodeproj - Crear un nuevo proyecto de Xcode

  • Parámetros: project_name, path, organization_name, bundle_identifier

• list_targets - Listar todos los targets de un proyecto

  • Parámetros: project_path

• list_build_configurations - Listar todas las configuraciones de compilación

  • Parámetros: project_path

• list_files - Listar todos los archivos de un target específico

  • Parámetros: project_path, target_name

• list_groups - Listar todos los grupos del proyecto con rutas jerárquicas, opcionalmente filtrados por target

  • Parámetros: project_path, target_name (opcional)

Operaciones de archivos

• add_file - Añadir un archivo al proyecto

  • Parámetros: project_path, file_path, target_name, group_path

• remove_file - Eliminar un archivo del proyecto

  • Parámetros: project_path, file_path

• move_file - Mover o renombrar un archivo dentro del proyecto

  • Parámetros: project_path, source_path, destination_path

• add_synchronized_folder - Añadir una referencia de carpeta sincronizada al proyecto

  • Parámetros: project_path, folder_path, group_name, target_name

• create_group - Crear un nuevo grupo en el navegador del proyecto

  • Parámetros: project_path, group_name, parent_group_path

Gestión de targets

• add_target - Crear un nuevo target

  • Parámetros: project_path, target_name, type, platform, bundle_identifier

• remove_target - Eliminar un target existente

  • Parámetros: project_path, target_name

• duplicate_target - Duplicar un target existente

  • Parámetros: project_path, source_target_name, new_target_name

• add_dependency - Añadir dependencia entre targets

  • Parámetros: project_path, target_name, dependency_name

Gestión de extensiones de app

• add_app_extension - Añadir un target de App Extension e incrustarlo en una app host

  • Parámetros: project_path, extension_name, extension_type, host_target_name, bundle_identifier, platform (opcional), deployment_target (opcional)
  • Tipos de extensión admitidos: widget, notification_service, notification_content, share, today, action, file_provider, intents, intents_ui, keyboard, photo_editing, document_provider, custom

• remove_app_extension - Eliminar un target de App Extension y su incrustación de la app host

  • Parámetros: project_path, extension_name

Configuración de compilación

• get_build_settings - Obtener ajustes de compilación de un target

  • Parámetros: project_path, target_name, configuration_name

• set_build_setting - Modificar ajustes de compilación

  • Parámetros: project_path, target_name, setting_name, value, configuration_name

• add_framework - Añadir dependencias de frameworks

  • Parámetros: project_path, target_name, framework_name, embed

• add_build_phase - Añadir fases de compilación personalizadas

  • Parámetros: project_path, target_name, phase_type, name, script

Gestión de Swift Packages

• add_swift_package - Añadir una dependencia de Swift Package al proyecto

  • Parámetros: project_path, package_url, requirement, target_name, product_name

• list_swift_packages - Listar todas las dependencias de Swift Package del proyecto

  • Parámetros: project_path

• remove_swift_package - Eliminar una dependencia de Swift Package del proyecto

  • Parámetros: project_path, package_url, remove_from_targets

Licencia

Este proyecto está licenciado bajo la Licencia MIT.