Claude Code Xcode 플러그인: 설치·연결과 MCP 오류 해결
Apple의 플러그인이나 수동 MCP 등록으로 Claude Code를 Xcode에 연결합니다. 로컬 내보내기 명령과 선택된 Xcode를 확인하고 외부 에이전트 접근을 허용한 뒤 실제 빌드로 연결을 검증합니다. 도구가 없는 원인을 진단하고 Codex를 연결하면서 플러그인 적용 범위와 모델 과금을 구분합니다.
목차

Claude Code에서 Swift 파일을 수정할 수 있어도 Xcode의 빌드, 테스트, 미리 보기에는 접근하지 못할 수 있습니다. Mac에서 Claude Code를 연결하기 전에 Xcode에서 외부 에이전트의 접근을 허용하고 프로젝트를 엽니다. 로컬 내보내기 명령이 작동하면 xcode@claude-plugins-official을 설치하고, 그렇지 않으면 Apple이 문서로 안내하는 xcrun mcpbridge 연결 방식을 사용합니다.
아래 절차는 2026-11-16 기준 공식 문서를 따릅니다. 권한 설정과 직접 MCP 연결은 Apple의 외부 에이전트 접근 안내에서 설명합니다.
설치 전에 Mac에서 선택된 Xcode를 확인합니다
전체 Xcode 앱을 설치하고 최신 Claude Code CLI를 사용합니다. 마켓플레이스 항목은 Mac에 있는 Xcode 도구에서 플러그인을 가져옵니다. 마켓플레이스 패키지를 설치한다고 설치되지 않은 Xcode까지 함께 제공되는 것은 아닙니다.
Bash에서 앱 저장소로 이동한 뒤 CLI 버전과 선택된 개발자 디렉터리를 확인합니다.
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 명령 자체를 찾을 수 없다면 Xcode를 진단하기 전에 Claude Code 설치와 첫 실행 확인부터 완료합니다.
외부 에이전트를 허용하고 프로젝트를 엽니다
Xcode의 Intelligence 설정에서 외부 프로세스의 접근을 허용합니다. 이 권한 설정은 Claude Code 플러그인 설치와 별개입니다.
- Xcode > Settings > Intelligence를 엽니다.
- Model Context Protocol에서 Allow External Agents to Use Xcode Tools를 While Xcode is Open 또는 Always로 설정합니다.
- 에이전트가 사용할 프로젝트나 워크스페이스를 엽니다.
이 대화형 작업에는 While Xcode is Open을 선택합니다. 아래 확인 절차를 진행하는 동안 프로젝트를 열린 상태로 유지합니다. Apple 문서에 따르면 외부 에이전트가 연결될 때와 작동 중일 때 Xcode가 알림을 표시합니다.
이미 작동하는 모델 연결도 유지합니다. 이용 조건에 맞는 Claude 구독에서는 요금제에 포함된 사용량이 차감되고, Claude Console 계정에서는 API 사용량이 별도로 청구됩니다. 기존 사용량 한도가 충분하면 구독을, 사용량 기준으로 결제하려면 API를 선택합니다. 유료 이용을 시작하기 전에 Claude Code 인증 방법과 Anthropic의 지역별 이용 조건을 확인합니다.
BetterToken도 사용량에 따라 결제하는 API 이용 방법입니다. 본인 계정과 콘솔에서 생성한 키를 준비하고, 문서에 안내된 Claude Code 설정을 적용합니다. API용 잔액을 별도로 충전해 사용하려는 경우에 선택합니다. 결제 전에 모델의 과금 단위, 결제 수단, 수수료를 확인해야 하며, Claude 구독은 포함되지 않습니다. 현재 모델 요금을 확인하고 콘솔에서 결제 조건을 확인합니다.
플러그인과 직접 MCP 연결 중 하나를 선택합니다
Xcode의 내보내기 명령이 작동하면 플러그인을 사용합니다. 브리지 연결만 필요하거나 내보내기 명령은 없지만 mcpbridge는 작동한다면 MCP 서버를 직접 등록합니다.
공식 마켓플레이스 항목에는 작성자가 Apple Inc.로 표시되어 있습니다. 플러그인 소스는 로컬에서 xcrun agent plugin path --plugin-format claude를 실행합니다. 반면 직접 연결 명령은 xcrun mcpbridge를 MCP 서버로 등록합니다.
이는 패키지 제공 방식의 차이이며, 어느 쪽의 빌드 결과가 더 좋다는 근거는 아닙니다. 플러그인에는 MCP 설정뿐 아니라 스킬과 다른 구성 요소가 포함될 수 있습니다. 스킬 목록이 고정되어 있거나 두 방식의 기능이 완전히 같다고 가정하지 말고 설치된 패키지를 확인합니다. 문제가 생겼을 때 원인을 구분하기 쉽도록 처음에는 한 가지 방식만 사용합니다.
xcode@claude-plugins-official을 설치합니다
저장소에서 claude를 실행해 Claude Code를 시작합니다. 아래 명령은 Bash가 아니라 Claude Code의 대화형 입력창에 입력합니다.
/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를 직접 등록합니다
Claude Code를 실행할 저장소에서 Bash를 열고 Apple의 등록 명령을 그대로 실행합니다.
claude mcp add --transport stdio xcode -- xcrun mcpbridge
claude mcp list
claude
이 명령은 표준 입력과 출력을 통해 로컬 프로세스에 연결하도록 등록합니다. 여기서 지정한 서버 이름은 xcode입니다. 대화형 세션에서 빌드를 요청하기 전에 /mcp를 실행해 연결 상태를 확인합니다.
기본 MCP 적용 범위는 현재 프로젝트로 한정됩니다. Claude Code는 설정을 프로젝트와 연결해 ~/.claude.json에 저장하며, 모든 저장소에 자동으로 적용하지는 않습니다. MCP 적용 범위 문서에서 이 차이를 설명합니다.
등록만으로 작동 여부를 확인할 수는 없습니다. 서버가 실제로 연결되고 Xcode에 열려 있는 프로젝트에서 작업할 수 있는지까지 확인해야 합니다.
앱 수정을 요청하기 전에 빌드부터 확인합니다
먼저 파일을 수정하지 않고 빌드하도록 요청합니다. 이렇게 하면 연결 문제와 모델이 도입할 수 있는 변경 사항을 구분할 수 있습니다.
연결된 Claude Code 세션에 다음 프롬프트를 입력합니다. 열린 프로젝트와 활성 스킴을 확인하고, 파일을 수정하지 않은 채 사용 가능한 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와 연결된 도구 목록에서 확인해야 합니다.
예를 들어 Apple의 Xcode 27 릴리스 노트에는 시뮬레이터 부팅, 앱 설치와 실행, 터치 입력, 스크린샷 촬영이 설명되어 있습니다. 화면을 조작하는 작업을 요청하기 전에 해당 도구를 에이전트가 사용할 수 있는지 확인합니다.
빌드를 확인한 다음에는 사용 가능한 테스트를 찾고 관련 테스트나 테스트 모음을 실행하도록 요청합니다. 뷰를 변경할 때는 기존 SwiftUI 미리 보기를 렌더링하도록 요청하고 반환된 미리 보기를 살펴봅니다. 작업이 성공했다는 설명만 받지 말고 테스트 결과나 미리 보기 자체를 확인합니다.
첫 작업의 범위는 좁게 유지합니다. 반복 빌드와 많은 진단 출력을 추가하기 전에 MCP 컨텍스트 비용 확인 절차를 이용해 재현 가능한 동일 작업을 비교합니다.
전체를 다시 설치하지 말고 문제가 생긴 부분을 해결합니다
결과에 맞는 항목을 선택합니다. 아래 확인 사항은 서로 다른 상황에 대한 대안이며, 모두 순서대로 실행해야 하는 절차가 아닙니다.
xcrun이 agent 또는 mcpbridge를 찾지 못합니다
먼저 xcode-select --print-path를 확인합니다. 이전 Xcode 버전이나 독립형 명령줄 도구 패키지가 선택되어 있으면 터미널이 열린 Xcode 창과 다른 도구 체인을 사용할 수 있습니다.
사용할 앱이 /Applications/Xcode.app에 설치되어 있다면 Bash에서 다음과 같이 선택합니다.
sudo xcode-select --switch /Applications/Xcode.app
설치 위치가 다르면 실제 경로를 지정합니다. 이 명령은 기본 개발자 디렉터리를 변경하므로 선택 결과를 확인하고 실패했던 명령을 다시 실행합니다.
agent plugin path를 여전히 사용할 수 없지만 직접 MCP 연결은 작동한다면 그 연결을 사용합니다. 둘 다 작동하지 않으면 필요한 도구를 제공하는 Xcode 버전을 설치하거나 선택합니다. Claude Code의 모델 인증 정보를 바꾸기 전에 이 부분부터 확인해야 합니다.
claude mcp list에 이름이 xcode인 항목이 없습니다
직접 연결했다면 서버를 추가한 저장소에서 명령을 실행합니다. 프로젝트에 한정된 등록 정보는 다른 저장소에 자동으로 나타나지 않습니다.
플러그인으로 연결했다면 claude plugin list를 확인한 뒤 Claude Code 내부에서 /mcp를 확인합니다. 단순한 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를 열린 상태로 유지하고 새 에이전트 세션을 시작한 뒤, 파일을 수정하지 않는 빌드 요청을 반복합니다.
서버 항목이 있다는 것은 설정이 존재한다는 뜻입니다. 에이전트가 올바른 프로젝트에 접근했는지는 반환된 프로젝트 정보와 빌드 결과로 확인합니다. 도구가 프로젝트 고유의 오류를 반환하면 해당 진단을 바탕으로 다음 조치를 결정합니다.
같은 Xcode 프로젝트에 Codex를 연결합니다
Codex 사용자는 Claude Code 마켓플레이스 플러그인을 설치하지 않고 Apple의 직접 MCP 연결 방식을 사용할 수 있습니다. Xcode의 권한 설정을 그대로 유지하고 프로젝트를 열어 둡니다.
Codex CLI를 설치하고 인증을 완료한 상태에서 Bash로 다음 명령을 실행합니다.
codex mcp add xcode -- xcrun mcpbridge
codex mcp list
codex
Codex 내부에서는 OpenAI의 MCP 문서에 안내된 대로 /mcp를 사용해 활성 서버를 확인합니다. 그런 다음 파일을 수정하지 않는 동일한 빌드 프롬프트를 입력하고 반환된 결과를 확인합니다.
나중에 외부 에이전트의 접근 권한을 취소하려면 Xcode의 Intelligence 설정으로 돌아갑니다. Allow External Agents to Use Xcode Tools에서 Never를 선택합니다.