Плагин Xcode для Claude Code: установка и устранение ошибок MCP
Подключите Claude Code к Xcode через плагин Apple или ручную регистрацию MCP-сервера. Проверьте команду экспорта плагина и выбранный Xcode, разрешите доступ внешним агентам и выполните сборку без изменений кода. Разберите причины отсутствия инструментов и подключите Codex, не смешивая область действия настроек с оплатой доступа к модели.
Содержание

Claude Code может править Swift-файлы, но при этом не иметь доступа к сборке, тестам и предпросмотру в Xcode. Чтобы подключить эти инструменты на своём Mac, разрешите доступ внешним агентам в Xcode и откройте проект. Затем установите xcode@claude-plugins-official, если локальная команда экспорта плагина работает; иначе используйте описанное Apple подключение через xcrun mcpbridge.
Инструкция опирается на официальную документацию по состоянию на 2026-11-16. Разрешения и прямое подключение по MCP описаны в руководстве Apple для внешних агентов.
Перед установкой проверьте, какой Xcode выбран на Mac
Для подключения нужны полноценный Xcode и актуальная версия консольного клиента Claude Code. Каталог плагинов берёт пакет из инструментов Xcode на вашем Mac. Установка плагина не заменяет установку самого Xcode.
В Bash перейдите в репозиторий приложения и проверьте версию клиента и выбранный каталог инструментов разработчика:
claude --version
xcode-select --print-path
Путь должен указывать на ту установку Xcode, которую вы собираетесь использовать. Значение /Library/Developer/CommandLineTools означает отдельный пакет консольных инструментов, а не приложение Xcode. Это различие объясняет руководство Apple по настройке консольных инструментов.
Затем выполните команду, которую использует каталог плагинов:
xcrun agent plugin path --plugin-format claude
При успешном выполнении команда выведет абсолютный путь к каталогу плагина. Не удаляйте и не перемещайте этот каталог: режим mode: "link" загружает созданные файлы прямо из него.
Согласно официальному журналу изменений, поддержка источников плагинов через локальную команду появилась в Claude Code 2.1.229. Используйте актуальный выпуск, а не закрепляйте эту старую версию. Для Xcode ориентируйтесь на успешное выполнение команды экспорта: наличие mcpbridge само по себе не подтверждает наличие agent plugin path.
Если не найдена сама команда claude, сначала выполните установку и проверку первого запуска Claude Code, а затем разбирайтесь с Xcode.
Разрешите доступ внешним агентам и откройте проект
Разрешите внешнему процессу обращаться к Xcode через настройки Intelligence. Установка плагина Claude Code сама по себе этого разрешения не выдаёт.
- Откройте Xcode > Settings > Intelligence.
- В разделе Model Context Protocol установите Allow External Agents to Use Xcode Tools в While Xcode is Open или Always.
- Откройте проект или рабочее пространство, с которым должен работать агент.
Для работы в открытом Xcode выберите While Xcode is Open. Не закрывайте проект во время проверок ниже. По документации Apple, Xcode уведомляет о подключении внешнего агента и показывает его активность.
Сохраните работающее подключение к модели. Если ваш тариф Claude поддерживает Claude Code, работа расходует лимит подписки; через Claude Console запросы к API оплачиваются отдельно. Выбирайте подписку, когда её лимита достаточно, или API, когда нужна оплата по использованию. Изучите способы авторизации Claude Code и перед оплатой проверьте региональные условия Anthropic.
Ещё один вариант с оплатой по использованию — BetterToken: нужны собственный аккаунт, ключ из консоли и настройка Claude Code по документации. Выбирайте его для доступа к API с отдельным балансом; подписка Claude в него не входит.
По данным BetterToken на 16 ноября 2026 года, баланс можно пополнять в рублях без иностранной кредитной или виртуальной карты. API BetterToken доступен из России без VPN; это условие не распространяется на сторонние сайты, загрузки, вход в аккаунты, маркетплейсы и обновления.
Проверьте актуальные цены моделей и единицы тарификации, а перед оплатой уточните в консоли способы оплаты, поддерживаемые карты и комиссии.
Выберите плагин или прямое подключение по MCP
Используйте плагин, если команда экспорта в вашем Xcode работает. Прямая регистрация MCP подойдёт, когда нужен только мост к Xcode или команда экспорта недоступна, но mcpbridge работает.
В официальной записи каталога автором указан Apple Inc. Источник плагина запускает локальную команду xcrun agent plugin path --plugin-format claude. При прямом подключении команда xcrun mcpbridge регистрируется как MCP-сервер.
Разница здесь в способе установки. Из неё не следует, что один вариант собирает приложение лучше другого. Вместе с настройками MCP плагин может содержать навыки (skills), то есть инструкции для агента, и другие компоненты. Проверьте установленный пакет: не считайте набор навыков постоянным и не предполагайте полного совпадения возможностей двух способов. Начните с одного варианта, чтобы проще находить причину сбоя.
Установите xcode@claude-plugins-official
Запустите Claude Code командой claude из репозитория. Следующую команду введите в интерактивном сеансе Claude Code, а не в Bash:
/plugin install xcode@claude-plugins-official
Просмотрите параметры установки. Для первой проверки выберите локальную область установки: плагин будет включён только для вас в этом репозитории. Перед подтверждением сравните показанную команду экспорта с командой выше. Выполните указание о перезагрузке из итогового сообщения установщика, если оно появится, либо начните новый сеанс Claude Code.
Затем проверьте установленный плагин из Bash в том же репозитории:
claude plugin list
claude plugin details xcode@claude-plugins-official
Убедитесь, что плагин включён, и изучите список его компонентов. Справочник команд плагинов описывает этот список, в том числе навыки и MCP-серверы.
В Claude Code выполните /mcp и проверьте сервер, который добавил плагин. Имена таких MCP-серверов имеют вид plugin:<plugin>:<server>; отдельной записи с именем xcode может не быть.
Чтобы позже изменить область установки или удалить пакет, воспользуйтесь руководством по установке, проверке и удалению плагинов.
Зарегистрируйте xcrun mcpbridge напрямую
В Bash, из репозитория, где вы будете запускать Claude Code, выполните команду регистрации из документации Apple:
claude mcp add --transport stdio xcode -- xcrun mcpbridge
claude mcp list
claude
Так вы зарегистрируете подключение к локальному процессу через стандартные потоки ввода и вывода. Имя сервера в этой команде — xcode. В интерактивном сеансе выполните /mcp и проверьте состояние подключения, прежде чем запрашивать сборку.
По умолчанию настройки MCP действуют только для текущего проекта. Claude Code хранит их в ~/.claude.json с привязкой к проекту и не применяет автоматически ко всем репозиториям. Подробнее об этом — в документации по области действия MCP.
Одной регистрации недостаточно. Убедитесь, что сервер подключается и может работать с проектом, открытым в Xcode.
Проверьте сборку до внесения изменений в приложение
Сначала запросите сборку без правок файлов. Это поможет отделить проблемы подключения от ошибок, которые могут возникнуть после изменений модели.
Отправьте следующий запрос в сеансе Claude Code с подключённым Xcode. Он просит определить открытый проект и активную схему, собрать её для доступного симулятора iOS и сообщить результат без изменения файлов.
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.
Проверьте, что агент действительно вызвал инструмент Xcode и получил результат сборки. В самом Xcode также должна отображаться активность внешнего агента. Даже ошибка компиляции в ответе может подтвердить, что подключение работает: тогда исправляйте ошибку проекта, а не переустанавливайте плагин.
В описании плагина перечислены сборка, запуск и тестирование схем, предпросмотр SwiftUI, работа с симуляторами и устройствами, журналы сборки, диагностика и поиск в документации Apple. Доступность конкретных операций проверяйте по своей версии Xcode и списку подключённых инструментов.
Например, в примечаниях к выпуску Xcode 27 описаны загрузка симуляторов, установка и запуск приложений, имитация касаний и создание снимков экрана. Перед задачей, требующей взаимодействия с интерфейсом, убедитесь, что соответствующие инструменты доступны агенту.
После проверки сборки попросите агента найти доступные тесты и запустить один подходящий тест или набор. Если меняете представление, попросите агента отрисовать существующий предпросмотр SwiftUI и проверьте полученный результат. Проверяйте сам отчёт тестов или предпросмотр, а не только сообщение агента об успехе.
Ограничьте первую задачу одной проверкой. Прежде чем переходить к повторным сборкам и большим объёмам диагностики, оцените расход контекста MCP на одной воспроизводимой задаче.
Исправляйте причину сбоя, а не переустанавливайте всё
Выберите вариант, соответствующий вашему результату. Эти проверки нужны для разных ситуаций; выполнять их все подряд не требуется.
xcrun не находит agent или mcpbridge
Сначала проверьте xcode-select --print-path. Если выбран старый Xcode или отдельный пакет консольных инструментов, терминал может использовать не тот набор инструментов, что открытое окно Xcode.
Если нужное приложение находится в /Applications/Xcode.app, выберите его в Bash:
sudo xcode-select --switch /Applications/Xcode.app
Если Xcode установлен в другом месте, укажите его фактический путь. Команда меняет каталог инструментов разработчика по умолчанию, поэтому проверьте выбор и повторите команду, которая завершилась ошибкой.
Если agent plugin path по-прежнему недоступна, но прямое подключение по MCP работает, используйте его. Если не работает ни один вариант, установите или выберите версию Xcode с нужными инструментами. Не начинайте с замены учётных данных для доступа Claude Code к модели.
В claude mcp list нет отдельной записи xcode
При прямом подключении запускайте команду из того репозитория, где добавили сервер. Настройки, привязанные к проекту, не появятся автоматически в другом репозитории.
При установке через плагин проверьте claude plugin list, затем /mcp внутри Claude Code. Ищите сервер с именем, включающим имя плагина, а не только xcode. Если плагин установлен, но выключен, включите его через /plugin и начните новый сеанс.
Если установщик не находит плагин в каталоге, обновите каталог из интерактивного сеанса Claude Code:
/plugin marketplace update claude-plugins-official
После обновления повторите установку. Если отсутствует сам каталог, сначала выполните /plugin marketplace add anthropics/claude-plugins-official. В руководстве Anthropic по устранению ошибок плагинов ошибки каталога отделены от неподдерживаемых типов источника.
Сервер подключён, но проект недоступен
Откройте нужный проект в Xcode и ещё раз проверьте Allow External Agents to Use Xcode Tools. Оставьте Xcode открытым, начните новый сеанс агента и повторите запрос на сборку без правок.
Запись о сервере подтверждает наличие настроек. А сведения об открытом проекте и результат сборки подтверждают, что агент добрался до нужного проекта. Если инструмент вернул ошибку самого проекта, разберите её в первую очередь.
Подключите Codex к тому же проекту Xcode
Для Codex используйте прямое подключение по MCP из документации Apple. Устанавливать плагин из каталога Claude Code не нужно. Сохраните разрешение в настройках Xcode и оставьте проект открытым.
После установки Codex CLI и настройки авторизации выполните в Bash:
codex mcp add xcode -- xcrun mcpbridge
codex mcp list
codex
Внутри Codex выполните /mcp, чтобы просмотреть активные серверы, как описано в документации OpenAI по MCP. Затем отправьте тот же запрос на сборку без правок и проверьте возвращённый результат.
Чтобы позже отозвать доступ внешних агентов, вернитесь в настройки Intelligence в Xcode и выберите Never в пункте Allow External Agents to Use Xcode Tools.