xcode-cli-skill

中文文档

CLI + Skill wrapper for the official Xcode 26.3+ MCP tools: a persistent mcp-proxy so the "Allow access to Xcode?" popup only appears once per boot, plus a Claude Code Skill that saves ~5K 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 pops up "Allow access to Xcode?" every few seconds — and because CLI agents spawn new processes with different PIDs, macOS never remembers your choice.

Root Cause

Each time an AI agent calls xcrun mcpbridge, macOS sees a fresh process (new PID) and triggers a new permission dialog. There's no way to permanently allow it.

The Fix

This tool interposes a persistent mcp-proxy process between the agent and Xcode. The proxy holds a long-lived connection to xcrun mcpbridge, so macOS only asks for permission once. The agent talks to the proxy over HTTP — no new PIDs, no more popups.

Agent ──HTTP──▶ mcp-proxy (persistent, single PID) ──stdio──▶ xcrun mcpbridge ──▶ Xcode
                    ▲
              Allow once, done forever

Problem 2: Save ~5K Tokens of Context

MCP tool definitions (~5K tokens for 20 tools) load into every conversation, whether you use them or not. By wrapping them as a Claude Code Skill, only a ~30-word description stays in context — full tool docs load on-demand.

Prerequisites

• macOS with Xcode 26.3+ (ships xcrun mcpbridge)
• Node.js 18+
• mcp-proxy (bridges stdio MCP to HTTP)
• pm2 (keeps mcp-proxy alive)

Quick Start

# 1. Install dependencies
uv tool install mcp-proxy   # or: pip install mcp-proxy
npm install -g pm2

# 2. Clone and install CLI
git clone https://github.com/dazuiba/xcode-cli-skill.git
cd xcode-cli-skill
npm link

# 3. Start the persistent proxy
pm2 start xcode-mcp-proxy.config.cjs
pm2 save

Click "Allow" once when prompted. That's it — never again.

Verify

# Make sure Xcode is open with a project
xcode-cli XcodeListWindows
xcode-cli BuildProject --tab-identifier windowtab1

AI Agent Integration

Claude Code (Skill)

Install the skill so Claude Code knows how to use xcode-cli:

mkdir -p ~/.claude/skills/xcode-cli
cp skills/xcode-cli/SKILL.md ~/.claude/skills/xcode-cli/SKILL.md

Restart Claude Code. The skill will be available as /xcode-cli.

Codex (Skill)

Install the skill globally, just like Claude Code:

mkdir -p ~/.codex/skills/xcode-cli
cp skills/xcode-cli/SKILL.md ~/.codex/skills/xcode-cli/SKILL.md

MCP Server (not recommended)

Both Claude Code and Codex support adding the proxy as an MCP server directly:

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

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

Note: This loads all 20 tool definitions into every conversation — you won't benefit from the ~5K tokens context savings. Use the Skill approach above instead.

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

How It Works

AI Agent ──bash──▶ xcode-cli ──HTTP──▶ mcp-proxy ──stdio──▶ xcrun mcpbridge ──▶ Xcode IDE

Component	Role
xcrun mcpbridge	Xcode's built-in MCP server (stdio transport)
mcp-proxy	Bridges stdio → HTTP on port 9876; the persistent process that eliminates permission popups
xcode-cli	CLI wrapper generated by mcporter, converts CLI args → MCP tool calls

License

MIT