XC-MCP: XCode CLI wrapper

XC-MCP: Intelligent Xcode MCP Server

Problem: MCP clients can't effectively use Xcode CLI tools because the build and simulator listing commands return more than 50,000 tokens, exceeding MCP limits.
Solution: Progressive disclosure with intelligent caching returns 2,000 tokens instead, achieving 96% reduction.
Result: Full Xcode tooling functionality without token overflow, 90% faster workflows.

gh-social

Quick Start

# Install and run
npm install -g xc-mcp
xc-mcp

# Or use without installation
npx xc-mcp

MCP Configuration (Claude Desktop):

claude mcp add xc-mcp -s user "npx xc-mcp"

Why This Exists

Raw Xcode CLI tools break MCP clients due to massive output:

simctl list: 57,000+ tokens (exceeds MCP limits)
xcodebuild logs: 135,000+ tokens (unusable)
No state memory between operations

XC-MCP solves this with progressive disclosure: return concise summaries first, full data on demand via cache IDs. This maintains complete functionality while respecting MCP token constraints.

Core Features

Progressive Disclosure System

Concise summaries by default: 96% token reduction for simulator lists
Full details on demand: Use cache IDs to access complete data
Smart filtering: Return only relevant information upfront
Token-efficient responses: Never exceed MCP client limits

Three-Layer Intelligent Cache

Simulator Cache: 1-hour retention with usage tracking and performance metrics
Project Cache: Remembers successful build configurations per project
Response Cache: 30-minute retention for progressive disclosure access

Smart Defaults & Learning

Build configuration memory: Learns successful settings per project
Simulator recommendations: Prioritizes recently used and optimal devices
Performance tracking: Records boot times, build success rates, optimization metrics
Adaptive intelligence: Improves suggestions based on usage patterns

Usage Examples

Progressive Simulator Management

Get instant simulator summary (2k tokens vs 57k):

{
  "tool": "simctl-list",
  "arguments": {"deviceType": "iPhone"}
}

Returns concise summary with cache ID for detailed access:

{
  "cacheId": "sim-abc123",
  "summary": {
    "totalDevices": 47,
    "availableDevices": 31,
    "bootedDevices": 1
  },
  "quickAccess": {
    "bootedDevices": [{"name": "iPhone 16", "udid": "ABC-123"}],
    "recentlyUsed": [...],
    "recommendedForBuild": [...]
  }
}

Access full details when needed:

{
  "tool": "simctl-get-details",
  "arguments": {
    "cacheId": "sim-abc123",
    "detailType": "available-only",
    "maxDevices": 10
  }
}

Smart Building with Configuration Memory

Build with automatic smart defaults:

{
  "tool": "xcodebuild-build",
  "arguments": {
    "projectPath": "./MyApp.xcworkspace",
    "scheme": "MyApp"
  }
}

Returns build summary with cache ID for full logs:

{
  "buildId": "build-xyz789",
  "success": true,
  "summary": {
    "duration": 7075,
    "errorCount": 0,
    "warningCount": 1
  },
  "nextSteps": [
    "Build completed successfully",
    "Smart defaults used: optimal simulator auto-selected",
    "Use 'xcodebuild-get-details' with buildId for full logs"
  ]
}

Cache Management

Monitor cache performance:

{"tool": "cache-get-stats", "arguments": {}}

Configure cache timeouts:

{
  "tool": "cache-set-config",
  "arguments": {"cacheType": "simulator", "maxAgeMinutes": 30}
}

Installation & Configuration

Prerequisites

macOS with Xcode command-line tools
Node.js 18+
Xcode 15+ recommended

Install Xcode CLI tools:

xcode-select --install

Installation Options

# Global install (recommended)
npm install -g xc-mcp

# Local development
git clone https://github.com/conorluddy/xc-mcp.git
cd xc-mcp && npm install && npm run build

MCP Client Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "xc-mcp": {
      "command": "npx",
      "args": ["xc-mcp"],
      "cwd": "/path/to/your/ios/project"
    }
  }
}

Tool Reference

Category	Tool	Description	Progressive Disclosure
Project Discovery	`xcodebuild-list`	List targets, schemes, configurations	✓
	`xcodebuild-showsdks`	Available SDKs	-
	`xcodebuild-version`	Xcode version info	-
Build Operations	`xcodebuild-build`	Build with smart defaults	✓ (via buildId)
	`xcodebuild-clean`	Clean build artifacts	-
	`xcodebuild-get-details`	Access cached build logs	-
Simulator Management	`simctl-list`	Simulator list with 96% token reduction	✓ (via cacheId)
	`simctl-get-details`	Progressive access to full simulator data	-
	`simctl-boot`	Boot with performance tracking	-
	`simctl-shutdown`	Graceful shutdown	-
Cache Management	`cache-get-stats`	Cache performance metrics	-
	`cache-set-config`	Configure cache timeouts	-
	`cache-clear`	Clear cached data	-
	`list-cached-responses`	View cached build/test results	-

Advanced Features

Performance Optimization

90% fewer repeated calls through intelligent caching
Boot time tracking for simulator performance optimization
Build trend analysis tracks success rates and timing
Usage pattern learning improves recommendations over time

Persistent State Management (Optional)

Enable file-based persistence for cache data across server restarts:

{"tool": "persistence-enable", "arguments": {}}

Environment Variables

XCODE_CLI_MCP_TIMEOUT: Operation timeout (default: 300s)
XCODE_CLI_MCP_LOG_LEVEL: Logging verbosity
XCODE_CLI_MCP_CACHE_DIR: Custom cache directory

Development

Build Commands

npm run build      # Compile TypeScript
npm run dev        # Development mode with watch
npm test           # Run test suite (80% coverage required)
npm run lint       # Code linting with auto-fix

Testing

Jest with ESM support
80% coverage threshold enforced
Pre-commit hooks ensure code quality

License & Support

MIT License. For issues and questions, open a GitHub issue.

XC-MCP solves MCP token overflow for Xcode tooling through progressive disclosure and intelligent caching.

Deploy Server

HTTP connection URL

security - not tested

license - not found

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

Problem: MCP clients can't efficiently use Xcode CLI tools because the build and simulator listing commands return more than 50k tokens, exceeding MCP limits. Solution: MCP tooling using progressive disclosure with intelligent caching.

Related MCP Servers

Toolhouse MCP Server
toolhouse-community
-
security
A
license
-
quality
This MCP server allows you to connect MCP clients with Toolhouse's tools.
Last updated -
14
MIT License
iOS simulators MCP
InditexTech
A
security
A
license
A
quality
A MCP server that enables LLMs to interact with iOS simulators through natural language commands.
Last updated -
233
Apache 2.0
XcodeMCP
lapfelix
A
security
A
license
A
quality
MCP server for Xcode build automation and log parsing that opens Xcode projects, triggers builds directly in Xcode, and parses build logs to extract errors and warnings.
Last updated -
24
53
39
Apache 2.0
macOS Simulator MCP Server
ohqay
-
security
F
license
-
quality
An MCP server that allows AI tools like Claude Desktop, Claude Code, and Cursor to visually interact with macOS applications by capturing screenshots and controlling the mouse and keyboard.
Last updated -
4

View all related MCP servers