Xcode MCP Server

Apple 생태계를 위한 Model Context Protocol Server

OpenCode, Codex, Claude Code를 Xcode에 연결하세요 — 단일 index.js로 제공되는 43개의 전문 도구

🌐 언어: English | Español

설치 • 도구 • OpenCode • Codex • Claude Code • 문서

이것은 무엇인가요?

Xcode MCP Server는 여러분의 AI IDE(OpenCode / Codex / Claude Code)와 Xcode + Apple 개발 도구를 연결하는 본격적이고 프로덕션 준비가 끝난 브리지입니다.

LLM은 이제 Swift 코드만 작성하지 않습니다. 빌드, 테스트, 프로파일링, 시뮬레이터·실기기 관리, 서명은 물론 정확한 라인의 Xcode 열기까지 수행합니다 — HTTP 서버 없이 MCP stdio만으로 말이죠.

기술 스택: ES Modules · @modelcontextprotocol/sdk@1.30 · StdioServerTransport · promisify(exec) · Yarn 4 Berry · Make

• ✅ 단일 파일 index.js (2250줄) — 빌드 단계나 컴파일 없이 한 파일로 감사할 수 있습니다. 셔뱅 #!/usr/bin/env node, node, yarn start 또는 npx로 실행할 수 있습니다.

• ✅ 엄격한 JSON Schema를 갖춘 43개 도구 (additionalProperties:false) + 전역 try/catch. 각 도구는 content: [{type:"text"}]를 반환하고 실패 시 isError:true를 반환합니다 — // TODO 없음.

• ✅ 완전한 Apple 지원 범위: xcodebuild, simctl(9), devicectl(2), xctrace(5개 템플릿), agvtool, security, osascript/xed.

• ✅ 현대적인 DX: 번들된 Yarn 4(.yarn/releases), help를 지원하는 자체 문서화 Makefile, 모듈식 docs/, macOS CI + make test 스모크 테스트.

• ✅ 멀티 클라이언트: 동일한 index.js가 수정 없이 OpenCode, Codex, Claude Code에서 작동합니다.

Related MCP server: Xcode MCP Server

✨ 기능

📋 목차

1. 요구 사항

2. 단계별 설치

3. 검증

4. OpenCode / Codex / Claude Code 사용법

5. 도구 (43)

6. Make 명령어

7. 문서

8. 아키텍처

9. 기여

📦 요구 사항

Linux/Windows: make lint만 작동합니다(Xcode 없음). CI는 이를 위해 syntax-linux 작업을 실행합니다.

🚀 단계별 설치

다음 순서를 정확히 따르세요. 블록 단위로 복사해서 붙여넣으세요.

단계 0 — Xcode 및 Node 확인

xcodebuild -version
# Xcode 15.4  Build version 15F31d

node --version
# v20.11.0 (or newer)

yarn --version
# 4.18.0 — if "command not found", run:
corepack enable
corepack prepare yarn@stable --activate
yarn --version

단계 1 — 저장소 클론

git clone https://github.com/YanxReal/Xcode-MPC.git
cd Xcode-MPC

단계 2 — 의존성 설치

방법 A — Make 사용(권장, 최신):

make install

make install이 수행하는 작업:

1. yarn을 감지하고, 없으면 corepack으로 설치합니다.

2. yarn install을 실행합니다(yarn.lock을 읽고 @modelcontextprotocol/sdk 설치).

3. chmod +x index.js를 실행합니다.

예상 출력:

➤ YN0000: · Yarn 4.18.0
➤ YN0000: ┌ Resolution step
➤ YN0000: └ Completed
➤ YN0000: · Done with warnings in 3s
✓ dependencies installed

방법 B — Yarn 직접 사용:

yarn install
chmod +x index.js

npm에서 전환하는 경우:

rm -f package-lock.json
yarn install

단계 3 — 환경 확인

make doctor

다음과 같이 표시되어야 합니다:

Node: v20.x
Yarn: 4.18.0
Xcode: Xcode 15.x
xcrun: xcrun version 70
...
✓ doctor complete

xcodebuild: command not found가 표시되면:

sudo xcode-select -s /Applications/Xcode.app

단계 4 — MCP 서버 검증

make lint
# ➜ node --check index.js
# ✓ lint ok

make test
# ➜ smoke test MCP...
# ✓ tools/list: 43 tools
# ✓ xcode_sync_strings OK
# ✓ xcode_certificates_check OK
# ✓ smoke test PASSED

또는 수동으로:

python3 scripts/smoke_test.py
# or
node scripts/smoke_test.mjs

단계 5 — AI 클라이언트 설정

하나를 선택하세요(또는 세 개 모두 — 동일한 index.js가 어디서든 작동합니다):

복사해서 붙여넣을 수 있는 JSON/TOML이 포함된 전체 단계별 안내:

• 📘 OpenCode → docs/opencode.md

• 📗 Codex → docs/codex.md

• 📙 Claude Code → docs/claude-code.md

단계 6 — 다시 시작하고 테스트

OpenCode / Codex / Claude Code를 다시 시작하고 다음을 입력하세요:

list the xcode tools

43개의 도구가 표시되고 로그에는 다음이 보여야 합니다:

✅ Xcode MCP Server started (stdio) — 43 tools registered

완료! 이제 다음과 같이 말할 수 있습니다:

Build MyApp with xcode_build scheme MyApp destination "platform=iOS Simulator,name=iPhone 15"

✅ 검증

# 1. Syntax
make lint

# 2. Smoke MCP (no Xcode needed, just Node)
make test

# 3. Apple environment
make doctor
# Checks: node, yarn, xcodebuild, xcrun, simctl, swiftlint, security, osascript

# 4. Visual inspector (optional)
make inspect
# or
yarn inspect
# Open http://localhost:6274 → tools/list → tools/call

🔧 OpenCode / Codex / Claude Code 사용법

OpenCode

~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/Users/YanxReal/Dev/Tools/Xcode-MPC/index.js"],
      "env": {}
    }
  }
}

Codex (OpenAI)

~/.codex/config.toml:

[mcp_servers.xcode]
command = "node"
args = ["/Users/YanxReal/Dev/Tools/Xcode-MPC/index.js"]

Claude Code (Anthropic)

claude mcp add xcode -- node /Users/YanxReal/Dev/Tools/Xcode-MPC/index.js
# verify
claude mcp list
# xcode: connected — 43 tools

또는 프로젝트별로 .mcp.json을 사용하려면:

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/Users/YanxReal/Dev/Tools/Xcode-MPC/index.js"]
    }
  }
}

각 클라이언트별 프롬프트 예시 → docs/opencode.md · docs/codex.md · docs/claude-code.md · 템플릿: .mcp.json.example · .codex-config.toml.example

🛠️ 도구 (43)

1. 빌드, 진단 및 정리

2. 테스트 및 커버리지

3. 시뮬레이터 xcrun simctl (9)

simctl_list (booted 필터), simctl_lifecycle (boot|shutdown|erase), simctl_install_launch, simctl_media_capture (screenshot|record), simctl_push_notification, simctl_location_mock, simctl_privacy_control, simctl_ui_appearance (light|dark), simctl_open_url

4. 물리적 기기 xcrun devicectl (2)

devicectl_list (--json), devicectl_logs (deviceUdid*, durationSeconds)

5. 프로파일링 xcrun xctrace (1)

xctrace_profile (template: Time Profiler|Allocations|Leaks|System Trace, timeLimitSeconds, outputFilePath*)

6. 버전 및 보안 (2)

agvtool_version_bump (bump_build|set_version|set_build), xcode_certificates_check (security find-identity)

7. Xcode GUI 편집기 (2)

xcode_get_active_file (AppleScript osascript), xcode_open_at_line (filePath*, line*, column — xed → xcode://)

8. 지역화 (1)

xcode_sync_strings (.xcstrings → missing / pendingTranslation / emptyValues)

9. 에셋 Assets.xcassets + actool (6)

asset_list_contents (*.colorset/*.imageset 목록), asset_manage_color (#RRGGBB Light + Dark), asset_manage_image (배율/벡터 + preserves-vector-representation), asset_read_info (Contents.json), asset_delete (안전), asset_validate_actool (xcrun actool --compile)

10. AppIcon 모든 Apple OS (1)

asset_generate_appicon (iOS, macOS, watchOS, tvOS, visionOS — 42개 슬롯, sips -z (만약 baseImagePath가 있으면))

11. 패키지 SPM / CocoaPods / Carthage (11)

package_resolve/update/list/read_resolved/reset_cache/compute_checksum, spm_add/remove_dependency, cocoapods_manage, carthage_manage, cocoapods_to_spm_migrate (Podfile→Package.swift)

JSON Schema + 복사-붙여넣기 예제가 포함된 전체 레퍼런스 → docs/tools.md

📖 Make 명령어

make help          # Show this pretty help (colors)
make install       # yarn install + chmod +x
make reinstall     # clean + install (from scratch)
make lint          # node --check index.js
make doctor        # Check Node/Yarn/Xcode/simctl/swiftlint/osascript
make test          # Smoke test MCP (43 tools + 2 calls)
make start         # yarn start (stdio)
make dev           # yarn dev (--watch)
make inspect       # MCP Inspector at http://localhost:6274
make clean         # Remove node_modules/.yarn/cache/build
make fmt           # prettier if available
make release VERSION=1.0.1  # bump + tag + push

자세한 내용 → docs/development.md

📚 문서

🧪 수동 스모크 테스트

# Without Make:
python3 scripts/smoke_test.py
# STDERR: ✅ Xcode MCP Server started — 43 tools
# ✓ tools/list: 43 tools
# ✓ xcode_sync_strings OK
# ✓ smoke test PASSED

# With Make:
make test

🏗️ 아키텍처

index.js (2250 lines, 1 file)
├── Shebang + Imports (MCP SDK, promisify(exec), fs, path, os)
├── Helpers: shellEscape, expandTilde, runCommand (try/catch + 10MB buffer), formatResult
├── TOOLS[43]: Strict JSON Schema (additionalProperties:false)
├── Handlers[43]: async handle_* with validation + fallbacks (xed→xcode://, swift-format→swiftlint)
├── Dispatcher: HANDLERS map + ListTools/CallTool (try/catch → isError:true)
└── Server: StdioServerTransport (stdin JSON-RPC, stdout JSON-RPC, stderr logs)

참조: docs/architecture.md — 단일 파일 선택과 OpenCode → stdin → handler → xcrun → stdout 흐름.

🤝 기여

# 1. Fork and branch
git checkout -b feat/my-tool

# 2. Develop: add to TOOLS + Handler + HANDLERS in index.js
make install && make lint && make test

# 3. Document in docs/tools.md + README.md

# 4. PR

이슈: 버그 리포트 · 기능 요청 · PR 템플릿

CI는 macos-14와 ubuntu-latest에서 실행됩니다 — PR은 자동으로 테스트됩니다.

📄 라이선스

MIT © YanxReal — LICENSE를 참조하세요.

🔗 링크

• 저장소: https://github.com/YanxReal/Xcode-MPC

• MCP 스펙: https://modelcontextprotocol.io

• SDK: https://github.com/modelcontextprotocol/typescript-sdk

• Yarn Berry: https://yarnpkg.com/getting-started

• Xcode: https://developer.apple.com/xcode/

Apple 생태계를 위해 ❤️로 제작됨 · Yarn 4 + Make + CI + Docs

도움이 되셨다면 GitHub에서 ⭐를 남겨주세요