xcode-cli-skill

中文文档

CLI + Skill wrapper for the official Xcode 26.3+ MCP tools: a long-lived xcode-cli-service so the "Allow access to Xcode?" popup stops showing up on every call, plus a Claude Code Skill that saves ~5 K tokens of context per conversation.

| Pain point | Solution | |------------|----------| | AI agents get a "Allow access to Xcode?" popup on every Xcode MCP call, and it never remembers | A persistent mcp-proxy process — macOS only asks once | | MCP tool definitions (20 tools, ~5K tokens) load into every conversation | Wrapped as a Claude Code Skill — loads on-demand |

Details

Problem 1: Permission Popup Spam

When AI agents (Claude Code, Codex, Cursor) call Xcode 26.3 MCP tools, macOS can keep popping up "Allow access to Xcode?" every few seconds. If the bridge process keeps changing, macOS does not treat it as the same long-lived integration.

Root Cause

The Xcode MCP bridge is process-bound. If every call goes through a fresh short-lived process, you get repeated permission prompts and a worse day-to-day workflow.

The Fix

This repo runs a persistent local bridge service in front of xcrun mcpbridge. The agent or terminal CLI talks to that stable HTTP endpoint, while xcode-cli-ctl manages the background service for you.

Agent / CLI ──HTTP──▶ local bridge service ──▶ xcrun mcpbridge ──▶ Xcode
                           ▲
                  managed by xcode-cli-ctl

Problem 2: Keep MCP Out of Every Conversation by Default

Raw MCP server integration is available, but it is not the recommended default. For Claude Code and Codex, this repo is primarily about the packaged xcode-cli Skill: let the agent load the workflow when it actually needs Xcode, instead of wiring raw MCP tools into every session.

Prerequisites

• macOS with Xcode 26.3+
• Node.js 18+
• Xcode open with the target project/workspace when you want to build, test, preview, or inspect issues

Quick Start

# 1. Install from npm
npm install -g xcode-cli@latest

# 2. Install and start the local bridge service
xcode-cli-ctl install

# 3. Check service health
xcode-cli-ctl status

# 4. Install the packaged skill
xcode-cli-ctl skill install

Click "Allow" when macOS asks for Xcode permission.

Verify

# Make sure Xcode is open with a project
xcode-cli windows
xcode-cli build

AI Agent Integration

use skill, you can saves ~5 K tokens of context per conversation.

Skill Installation (better)

xcode-cli-ctl skill install --claude
xcode-cli-ctl skill install --codex
# Install to both Claude Code and Codex
xcode-cli-ctl skill install

# Or copy manually
cp skills/xcode-cli/SKILL.md ~/.claude/skills/xcode-cli/SKILL.md

MCP Server

# Claude Code
claude mcp add --transport http xcode http://localhost:48321/mcp

# Codex
codex mcp add xcode --url http://localhost:48321/mcp

Available Tools (20) provided by Xcode 26.3+

| Category | Tools | |----------|-------| | Build & Diagnostics | BuildProject, GetBuildLog, XcodeRefreshCodeIssuesInFile, XcodeListNavigatorIssues | | File Operations | XcodeRead, XcodeWrite, XcodeUpdate, XcodeRM, XcodeMV, XcodeMakeDir, XcodeLS | | Search | XcodeGrep, XcodeGlob, DocumentationSearch | | Testing | GetTestList, RunAllTests, RunSomeTests | | Preview & Execution | RenderPreview, ExecuteSnippet | | Workspace | XcodeListWindows |

Component List

| | Role | |-----------|------| | xcrun mcpbridge | Xcode's built-in MCP bridge | | xcode-cli-service | Persistent HTTP bridge on port 48321, managed by xcode-cli-ctl — solves the repeated permission popup | | xcode-cli | CLI for Xcode MCP workflows, used by the Skill and directly from the terminal | | SKILL.md | Recommended integration for Claude Code / Codex, installed via xcode-cli-ctl skill install | | xcode-cli-ctl | Manages service lifecycle and Skill installation |

License

MIT