XcodeProj MCP Server

Um servidor MCP para manipular arquivos de projeto Xcode (.xcodeproj) usando Swift. Requer Docker e macOS.

GitHub

133

Experimente este MCPPatrocinado

Documentação

xcodeproj-mcp-server

Um servidor Model Context Protocol (MCP) para manipular arquivos de projeto Xcode (.xcodeproj) usando Swift.

Adding Post Build Phase for all targets

Visão Geral

xcodeproj-mcp-server é um servidor MCP que fornece ferramentas para manipular programaticamente arquivos de projeto Xcode. Ele utiliza a biblioteca tuist/xcodeproj para manipulação confiável de arquivos de projeto e implementa o Model Context Protocol usando o swift-sdk.

Este servidor permite que assistentes de IA e outros clientes MCP:

Criem novos projetos Xcode
Gerenciem targets, arquivos e configurações de build
Inspecionem a estrutura do projeto, incluindo grupos e hierarquias
Modifiquem configurações de build
Adicionem dependências e frameworks
Automatizem tarefas comuns de projetos Xcode

Casos de Uso

Criação e Configuração de Projetos

Criar projetos do zero: Gere novos projetos Xcode com configurações personalizadas, bundle identifiers e configurações de organização sem abrir o Xcode
Estruturação de projetos multi-target: Configure projetos complexos com múltiplos apps, frameworks, testes e extensões em um único fluxo de trabalho automatizado

Automação do Fluxo de Trabalho de Desenvolvimento

Adicionar novos arquivos a targets: Após criar um novo arquivo Swift, adicione-o automaticamente aos arquivos de origem do target apropriado para compilação
Adicionar referências de pastas: Inclua pastas de recursos externos ou diretórios de assets como referências de pastas sincronizadas no seu projeto, refletindo automaticamente quaisquer alterações no sistema de arquivos
Adicionar fases de build: Integre formatadores de código, linters ou scripts de build personalizados aos seus targets (por exemplo, fases de execução do SwiftLint, SwiftFormat)
Criar frameworks e extensões de app: Estruture rapidamente novos targets de framework ou extensões de app para modularizar sua base de código
Adicionar Widget Extensions: Crie e incorpore automaticamente targets de Widget Extension com configuração adequada para widgets da tela inicial do iOS

Gerenciamento de Configuração de Projetos

Automatizar configuração do Info.plist: Configure programaticamente as configurações do Info.plist, entitlements e perfis de provisionamento para diferentes targets
Gerenciamento de configurações de build: Configure diferentes configurações de build com flags de compilador apropriadas, bundle identifiers e deployment targets
Gerenciamento de dependências: Adicione frameworks do sistema, bibliotecas de link e configure dependências de targets sem navegação manual no Xcode

Como configurar para Claude Desktop e Claude Code

Pré-requisitos

macOS (para executar projetos Xcode)
Um runtime de contêiner — container da Apple (recomendado) ou Docker

O servidor é distribuído como uma imagem de contêiner linux/arm64, que executa em qualquer um dos runtimes.

Configuração com o `container` da Apple (recomendado)

container é a ferramenta da Apple para executar contêineres Linux como máquinas virtuais leves no macOS. É o runtime recomendado para este servidor: vem da Apple, não requer aplicativo de desktop de terceiros e executa a imagem linux/arm64 publicada nativamente em Apple silicon.

Requisitos

Um Mac com Apple silicon
macOS 26 ou posterior (o container não suporta versões mais antigas)

Instalação

Instale a CLI do container na página oficial de releases.

O container precisa do serviço em segundo plano em execução. Inicie-o uma vez após a instalação e novamente após cada reinicialização:

container system start

Em seguida, baixe a imagem pré-construída do GitHub Container Registry:

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

O container run não tem opção de --pull, então execute container image pull novamente sempre que quiser atualizar para a imagem mais recente.

Configuração para Claude Code

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

Isso monta o diretório do projeto em /workspace dentro do contêiner, que é como o servidor obtém acesso aos seus projetos Xcode. Mantenha as aspas simples: elas impedem que seu shell expanda a montagem no momento do registro, para que o Claude Code a resolva toda vez que iniciar o servidor, em vez de fixá-la no diretório de onde você executou o claude mcp add. Ele usa como fallback o ., o diretório de trabalho em que o Claude Code inicia o servidor, que é a raiz do projeto.

Configuração para Claude Desktop

Adicione o seguinte ao seu arquivo de configuração do 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"
      ]
    }
  }
}

O instalador coloca o binário em /usr/local/bin/container. O caminho absoluto é usado aqui porque esse diretório nem sempre está no PATH de aplicativos GUI.

Construindo a imagem localmente

O container build lê o mesmo Dockerfile:

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

O contêiner de build usa por padrão 2 CPUs e 2 GB de memória. Aloque mais para acelerar o build de release:

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

Configuração com Docker

Use Docker se você estiver no macOS 15 ou anterior, ou se o Docker já fizer parte do seu fluxo de trabalho.

Baixe a imagem Docker pré-construída do GitHub Container Registry:

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

Configuração 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

Assim como no container, o diretório do projeto é montado em /workspace dentro do contêiner para que o servidor possa acessar seus projetos Xcode, e as aspas simples mantêm a montagem sem expansão até o Claude Code iniciar o servidor.

Configuração para Claude Desktop

Adicione o seguinte ao seu arquivo de configuração do 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 o servidor a partir do Claude Code ou Codex dentro do Xcode

O Xcode pode executar Claude Code e Codex como agentes de codificação, e lê a configuração deles de subpastas específicas de agente em ~/Library/Developer/Xcode/CodingAssistant, uma pasta que o Xcode usa exclusivamente. A configuração colocada lá afeta os agentes apenas quando você os inicia no Xcode, portanto não interfere na sua configuração regular de ~/.claude ou ~/.codex. Consulte Extending and customizing agents da Apple para obter detalhes.

Duas coisas diferem da configuração de linha de comando:

O Xcode inicia o servidor MCP com o diretório do projeto como diretório de trabalho, então monte . diretamente. O Codex não tem equivalente à expansão de ${CLAUDE_PROJECT_DIR:-.} do Claude Code, então isso mantém ambos os agentes na mesma montagem.
Dê ao command um caminho absoluto, porque o ambiente do agente não tem necessariamente o /usr/local/bin no seu PATH.

Claude Code no Xcode

O ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig atua como diretório de configuração do Claude Code. Aponte o CLAUDE_CONFIG_DIR para ele e use 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

Isso grava o servidor em ClaudeAgentConfig/.claude.json. Para adicioná-lo manualmente, adicione uma entrada em 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 no Xcode

O ~/Library/Developer/Xcode/CodingAssistant/codex atua como o CODEX_HOME do 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

Isso grava o servidor em codex/config.toml. Para adicioná-lo manualmente:

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

Se você configurou com Docker, use o caminho absoluto para o binário do seu docker no lugar de /usr/local/bin/container. Reinicie o agente no Xcode após alterar a configuração.

Configurações recomendadas para Claude Code

Ativar o ENABLE_TOOL_SEARCH no .claude/settings.json ativa o carregamento dinâmico de ferramentas MCP. Isso evita que ferramentas MCP não utilizadas consumam contexto.

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

Segurança de Caminhos

O servidor MCP agora suporta restringir operações de arquivo a um diretório base específico. Quando você fornece um caminho base como argumento de linha de comando:

Todos os parâmetros de project_path e caminhos de arquivo serão resolvidos em relação a este caminho base
Caminhos absolutos são validados para garantir que estejam dentro do diretório base
Qualquer tentativa de acessar arquivos fora do diretório base resultará em erro

Isso é especialmente útil ao executar o servidor em contêineres ou outros ambientes com sandbox.

Ferramentas Disponíveis

Gerenciamento de Projetos

create_xcodeproj - Criar um novo projeto Xcode
- Parâmetros: project_name, path, organization_name, bundle_identifier
list_targets - Listar todos os targets em um projeto
- Parâmetros: project_path
list_build_configurations - Listar todas as configurações de build
- Parâmetros: project_path
list_files - Listar todos os arquivos em um target específico
- Parâmetros: project_path, target_name
list_groups - Listar todos os grupos no projeto com caminhos hierárquicos, opcionalmente filtrados por target
- Parâmetros: project_path, target_name (opcional)

Operações de Arquivo

add_file - Adicionar um arquivo ao projeto
- Parâmetros: project_path, file_path, target_name, group_path
remove_file - Remover um arquivo do projeto
- Parâmetros: project_path, file_path
move_file - Mover ou renomear um arquivo dentro do projeto
- Parâmetros: project_path, source_path, destination_path
add_synchronized_folder - Adicionar uma referência de pasta sincronizada ao projeto
- Parâmetros: project_path, folder_path, group_name, target_name
create_group - Criar um novo grupo no navegador do projeto
- Parâmetros: project_path, group_name, parent_group_path

Gerenciamento de Targets

add_target - Criar um novo target
- Parâmetros: project_path, target_name, type, platform, bundle_identifier
remove_target - Remover um target existente
- Parâmetros: project_path, target_name
duplicate_target - Duplicar um target existente
- Parâmetros: project_path, source_target_name, new_target_name
add_dependency - Adicionar dependência entre targets
- Parâmetros: project_path, target_name, dependency_name

Gerenciamento de Extensões de App

add_app_extension - Adicionar um target de App Extension e incorporá-lo em um app host
- Parâmetros: project_path, extension_name, extension_type, host_target_name, bundle_identifier, platform (opcional), deployment_target (opcional)
- Tipos de extensão suportados: widget, notification_service, notification_content, share, today, action, file_provider, intents, intents_ui, keyboard, photo_editing, document_provider, custom
remove_app_extension - Remover um target de App Extension e sua incorporação do app host
- Parâmetros: project_path, extension_name

Configuração de Build

get_build_settings - Obter configurações de build para um target
- Parâmetros: project_path, target_name, configuration_name
set_build_setting - Modificar configurações de build
- Parâmetros: project_path, target_name, setting_name, value, configuration_name
add_framework - Adicionar dependências de framework
- Parâmetros: project_path, target_name, framework_name, embed
add_build_phase - Adicionar fases de build personalizadas
- Parâmetros: project_path, target_name, phase_type, name, script

Gerenciamento de Swift Packages

add_swift_package - Adicionar uma dependência de Swift Package ao projeto
- Parâmetros: project_path, package_url, requirement, target_name, product_name
list_swift_packages - Listar todas as dependências de Swift Package no projeto
- Parâmetros: project_path
remove_swift_package - Remover uma dependência de Swift Package do projeto
- Parâmetros: project_path, package_url, remove_from_targets

Licença

Este projeto está licenciado sob a Licença MIT.

XcodeProj MCP Server

Documentação

xcodeproj-mcp-server

Visão Geral

Casos de Uso

Criação e Configuração de Projetos

Automação do Fluxo de Trabalho de Desenvolvimento

Gerenciamento de Configuração de Projetos

Como configurar para Claude Desktop e Claude Code

Pré-requisitos

Configuração com o container da Apple (recomendado)

Requisitos

Instalação

Configuração para Claude Code

Configuração para Claude Desktop

Construindo a imagem localmente

Configuração com Docker

Configuração para Claude Code

Configuração para Claude Desktop

Usando o servidor a partir do Claude Code ou Codex dentro do Xcode

Claude Code no Xcode

Codex no Xcode

Configurações recomendadas para Claude Code

Segurança de Caminhos

Ferramentas Disponíveis

Gerenciamento de Projetos

Operações de Arquivo

Gerenciamento de Targets

Gerenciamento de Extensões de App

Configuração de Build

Gerenciamento de Swift Packages

Licença

Configuração com o `container` da Apple (recomendado)