Xcode MCP Server

Apple エコシステム向け Model Context Protocol サーバー

OpenCode、Codex、Claude Code を Xcode に接続 — 1 つの index.js に 43 個のプロフェッショナルツール

🌐 言語: English | Español

インストール • ツール • OpenCode • Codex • Claude Code • ドキュメント

これは何ですか？

Xcode MCP Server は、AI IDE（OpenCode / Codex / Claude Code）と Xcode + Apple Dev Tools を結ぶ、本格的で本番対応のブリッジです。

LLM はもはや Swift を書くだけではありません。ビルド、テスト、プロファイリング、シミュレータ・実機・署名の管理、さらには該当行で Xcode を開くことまで、HTTP サーバーなしで MCP stdio 経由で行います。

スタック: ES Modules · @modelcontextprotocol/sdk@1.30 · StdioServerTransport · promisify(exec) · Yarn 4 Berry · Make

• ✅ 単一ファイルの index.js（2250 行） — ビルドステップやコンパイルは不要、1 つのファイルで監査可能。シバン #!/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 クライアントの設定

いずれか 1 つ（または 3 つすべて — 同じ 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スロット、baseImagePathがある場合はsips -z)

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)

単一ファイルの決定、OpenCode → stdin → handler → xcrun → stdoutフローについては、docs/architecture.mdを参照してください。

🤝 コントリビューション

# 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で⭐をお願いします