Plugin do Xcode no Claude Code: instalação e erros de MCP
Conecte o Claude Code ao Xcode pelo plugin da Apple ou pelo registro manual de MCP. Verifique o comando de exportação local e a instalação selecionada do Xcode, permita agentes externos e valide um build real. Resolva ferramentas ausentes e conecte o Codex sem confundir o escopo do plugin com a cobrança pelo modelo.
Conteúdo

O Claude Code pode editar arquivos Swift e ainda não ter acesso a builds, testes e prévias do Xcode. No Mac, permita o acesso de agentes externos no Xcode e abra o projeto antes de conectar o Claude Code. Instale xcode@claude-plugins-official se o comando local de exportação funcionar; caso contrário, use a conexão com xcrun mcpbridge documentada pela Apple.
As instruções abaixo seguem a documentação oficial disponível em 2026-11-16. O guia da Apple para agentes externos explica as permissões e a conexão direta por MCP.
Confira qual Xcode está selecionado no Mac antes de instalar
Use uma instalação completa do Xcode e uma versão atual do Claude Code CLI. A entrada do marketplace obtém o plugin das ferramentas do Xcode instaladas no Mac. Instalar o pacote do marketplace não instala o Xcode caso ele esteja ausente.
No Bash, a partir do repositório do aplicativo, confira a versão do cliente e o diretório de desenvolvimento selecionado:
claude --version
xcode-select --print-path
O diretório de desenvolvimento deve pertencer à instalação do Xcode que você pretende usar. O resultado /Library/Developer/CommandLineTools identifica o pacote separado de ferramentas de linha de comando, não o aplicativo Xcode. O guia da Apple para configurar as ferramentas de linha de comando explica essa diferença.
Em seguida, execute o mesmo comando usado pelo marketplace:
xcrun agent plugin path --plugin-format claude
Quando funciona, o comando de exportação exibe o caminho absoluto do diretório do plugin. Mantenha esse diretório intacto: o marketplace usa mode: "link", que carrega os arquivos gerados no próprio local.
O Claude Code adicionou fontes de plugins baseadas em comandos na versão 2.1.229, segundo o histórico oficial de alterações. Use uma versão atual em vez de fixar aquela versão antiga. Para o Xcode, confirme que a verificação do comando de exportação passa. Não presuma que uma instalação com mcpbridge também oferece agent plugin path.
Se o próprio comando claude estiver ausente, conclua a instalação e as verificações da primeira execução do Claude Code antes de diagnosticar o Xcode.
Permita agentes externos e abra o projeto
Autorize o acesso do processo externo nas configurações Intelligence do Xcode. Essa permissão é separada da instalação de um plugin do Claude Code.
- Abra Xcode > Settings > Intelligence.
- Em Model Context Protocol, defina Allow External Agents to Use Xcode Tools como While Xcode is Open ou Always.
- Abra o projeto ou workspace que o agente deve usar.
Escolha While Xcode is Open para esse uso interativo. Mantenha o projeto aberto durante as verificações abaixo. Segundo a documentação da Apple, o Xcode avisa quando um agente externo se conecta e enquanto ele está ativo.
Mantenha também a conexão com o modelo que já funciona. Uma assinatura elegível do Claude usa a cota do plano; uma conta do Claude Console permite usar a API com cobrança separada. Escolha a assinatura se a cota atual for suficiente, ou a API para pagar conforme o uso. Consulte a autenticação do Claude Code e confira a disponibilidade regional da Anthropic antes de pagar pelo acesso.
O BetterToken é outra opção de API com pagamento por uso. Você precisa da própria conta, de uma chave criada no console e da configuração documentada para o Claude Code. Escolha essa opção para usar a API com um saldo separado. Antes de pagar, confira as unidades de cobrança do modelo, os meios de pagamento e as taxas. A opção não inclui uma assinatura do Claude. Confira os preços atuais dos modelos e confirme as condições de pagamento no console.
Escolha o plugin ou a conexão direta por MCP
Use o plugin se o comando de exportação do seu Xcode funcionar. Registre o MCP diretamente quando precisar apenas da conexão pela ponte ou quando a exportação estiver indisponível, mas mcpbridge funcionar.
A entrada oficial do marketplace indica Apple Inc. como autora. A fonte do plugin executa xcrun agent plugin path --plugin-format claude localmente. Já o comando de conexão direta registra xcrun mcpbridge como servidor MCP.
Essa é uma diferença de empacotamento, não uma evidência de que uma opção produz builds melhores. Um plugin pode incluir habilidades (skills) e outros componentes junto com a configuração MCP. Inspecione o pacote instalado em vez de presumir uma lista fixa de habilidades ou equivalência completa de recursos. Comece com uma única opção para facilitar a identificação de falhas.
Instale xcode@claude-plugins-official
Inicie o Claude Code no repositório com claude. Digite o comando abaixo na sessão interativa dele, não no Bash:
/plugin install xcode@claude-plugins-official
Revise as opções de instalação e escolha o escopo local para um primeiro teste limitado ao repositório. Antes de autorizar o comando de exportação exibido, confira se ele corresponde ao comando acima. Siga qualquer instrução de recarga no resumo da instalação ou inicie uma nova sessão do Claude Code.
Depois, confira a instalação pelo Bash no mesmo repositório:
claude plugin list
claude plugin details xcode@claude-plugins-official
Verifique se o pacote está habilitado e examine a lista de componentes. A referência de comandos de plugins descreve essa lista, incluindo habilidades e servidores MCP.
No Claude Code, execute /mcp e inspecione o servidor fornecido pelo plugin. Servidores MCP de plugins usam nomes no formato plugin:<plugin>:<server>; não é obrigatório aparecer uma entrada chamada apenas xcode.
Para mudar o escopo ou remover o pacote depois, consulte o guia de instalação, verificação e remoção de plugins.
Registre xcrun mcpbridge diretamente
Use o comando exato de registro da Apple no Bash, a partir do repositório em que você executará o Claude Code:
claude mcp add --transport stdio xcode -- xcrun mcpbridge
claude mcp list
claude
Isso registra uma conexão com um processo local pela entrada e saída padrão. O nome do servidor escolhido no comando é xcode. Na sessão interativa, execute /mcp e confira o estado da conexão antes de pedir um build.
Por padrão, o escopo do MCP é local ao projeto. O Claude Code salva essa configuração em ~/.claude.json, vinculada ao projeto, sem aplicá-la automaticamente a todos os repositórios. A documentação sobre escopos de MCP explica essa diferença.
O registro, por si só, não confirma que a conexão funciona. Verifique se o servidor se conecta e consegue trabalhar com o projeto aberto no Xcode.
Verifique um build antes de pedir alterações no aplicativo
Primeiro, peça um build sem editar arquivos. Isso separa problemas de conexão das alterações que o modelo pode introduzir.
Envie o prompt abaixo na sessão do Claude Code conectada ao Xcode. Ele pede a identificação do projeto e do esquema ativo, um build para um simulador disponível e o resultado sem editar arquivos:
Use Xcode tools to identify the open project and active scheme.
Build that scheme for an available iOS Simulator destination.
Do not edit files.
Report the build result and the first actionable error, if any.
Procure uma chamada real a uma ferramenta do Xcode e o resultado do build retornado por ela. O Xcode também deve indicar a atividade do agente externo. Um erro do compilador pode confirmar que a conexão funciona, mesmo que o aplicativo ainda não compile. Nesse caso, corrija o erro do projeto em vez de reinstalar o plugin.
O marketplace descreve builds, execução e testes de esquemas; renderização de prévias do SwiftUI; operações com simuladores e dispositivos; logs de build, diagnósticos e busca na documentação da Apple. Confira quais operações estão disponíveis na sua instalação do Xcode e na lista de ferramentas conectadas.
Por exemplo, as notas de versão do Xcode 27 documentam a inicialização de simuladores, a instalação e execução de aplicativos, entradas por toque e capturas de tela. Verifique se as ferramentas correspondentes estão disponíveis antes de pedir uma tarefa que interaja com a interface.
Após verificar o build, peça ao agente que identifique os testes disponíveis e execute um teste ou conjunto relevante. Para alterar uma visualização, peça a renderização de uma prévia existente do SwiftUI e inspecione o resultado retornado. Confira o resultado dos testes ou a própria prévia, não apenas uma afirmação de que a tarefa deu certo.
Mantenha a primeira tarefa limitada. Antes de adicionar builds repetidos e grandes volumes de diagnóstico, use o procedimento para medir o custo de contexto do MCP em uma tarefa reproduzível.
Corrija o componente com falha, não a instalação inteira
Escolha a verificação que corresponde ao seu resultado. São alternativas para situações diferentes, não uma sequência que todos precisam executar.
xcrun não encontra agent ou mcpbridge
Confira primeiro xcode-select --print-path. Se um Xcode antigo ou o pacote separado de ferramentas de linha de comando estiver selecionado, o terminal pode usar ferramentas diferentes das da janela aberta do Xcode.
Se o aplicativo desejado estiver instalado em /Applications/Xcode.app, selecione-o no Bash:
sudo xcode-select --switch /Applications/Xcode.app
Se a instalação estiver em outro local, use o caminho real. Isso muda o diretório de desenvolvimento padrão. Confirme a seleção e execute novamente o comando que falhou.
Se agent plugin path continuar indisponível, mas a conexão direta por MCP funcionar, use essa conexão. Se nenhuma opção funcionar, instale ou selecione uma versão do Xcode com as ferramentas necessárias antes de alterar as credenciais do modelo no Claude Code.
claude mcp list não mostra uma entrada chamada apenas xcode
Para a conexão direta, execute o comando no repositório em que você adicionou o servidor. Um registro local ao projeto não aparecerá automaticamente em outro repositório.
Para o plugin, confira claude plugin list e depois /mcp dentro do Claude Code. Procure um servidor com o nome do plugin, não apenas uma entrada xcode. Se o plugin estiver instalado, mas desativado, habilite-o por /plugin e inicie uma nova sessão.
Se o instalador não encontrar a entrada no marketplace, atualize o catálogo na sessão do Claude Code:
/plugin marketplace update claude-plugins-official
Repita a instalação após a atualização. Se o próprio marketplace estiver ausente, execute primeiro /plugin marketplace add anthropics/claude-plugins-official. O guia da Anthropic para resolver problemas de plugins diferencia esses erros de catálogo dos tipos de fonte não suportados.
O servidor se conecta, mas o projeto está indisponível
Abra o projeto desejado no Xcode e confira novamente Allow External Agents to Use Xcode Tools. Mantenha o Xcode aberto, inicie uma nova sessão do agente e repita o pedido de build sem alterações.
A entrada do servidor confirma que existe uma configuração. As informações do projeto e o resultado do build confirmam que o agente acessou o projeto correto. Se a ferramenta retornar um erro específico do projeto, use esse diagnóstico para orientar o próximo passo.
Conecte o Codex ao mesmo projeto do Xcode
Usuários do Codex podem usar a conexão direta por MCP documentada pela Apple sem instalar o plugin do marketplace do Claude Code. Mantenha a mesma permissão no Xcode e deixe o projeto aberto.
Com o Codex CLI instalado e autenticado, execute estes comandos no Bash:
codex mcp add xcode -- xcrun mcpbridge
codex mcp list
codex
Dentro do Codex, use /mcp para inspecionar os servidores ativos, conforme a documentação da OpenAI sobre MCP. Depois, envie o mesmo pedido de build sem alterações e examine o resultado retornado.
Para revogar o acesso de agentes externos, volte às configurações Intelligence do Xcode e selecione Never em Allow External Agents to Use Xcode Tools.