MCP server that wraps Xcode command-line tools for iOS/macOS development workflows
npm install mcp-xcodeA Model Context Protocol (MCP) server that provides intelligent, stateful access to Xcode command-line tools with revolutionary progressive disclosure that solves token overflow issues while maintaining full functionality through smart caching and adaptive intelligence.
Real-world results solving critical MCP token limits:
- ā
96% Token Reduction: 57,827 tokens ā 2,000 tokens for simulator listing
- ā
99.6% Build Log Reduction: 135,229 tokens ā 500 tokens for build results
- ā” 90% Faster Operations: Intelligent caching eliminates repeated expensive calls
- š§ Smart Learning: Remembers successful configurations and suggests optimal settings
- š Progressive Disclosure: Full details available on-demand via cache IDs
- šÆ Instant Recommendations: Booted devices and recently used simulators prioritized
simctl list callsbash
xcode-select --install
`$3
`bash
Install globally for CLI usage
npm install -g xc-mcpOr use with NPX (no installation required)
npx xc-mcp
`$3
`bash
git clone https://github.com/conorluddy/xc-mcp.git
cd xc-mcp
npm install
npm run build
`Usage
$3
#### From NPM/NPX Install
`bash
If installed globally
xc-mcpOr with NPX
npx xc-mcp
`#### From Local Development
`bash
npm start
`$3
`bash
npm run dev
`Intelligent Tool Usage Examples
$3
#### Check Cache Status
`json
{
"tool": "cache-get-stats",
"arguments": {}
}
`Response shows comprehensive cache metrics:
`json
{
"simulator": {
"isCached": true,
"deviceCount": 45,
"recentlyUsedCount": 8,
"cacheMaxAgeHuman": "1h"
},
"project": {
"projectCount": 3,
"buildHistoryCount": 12,
"cacheMaxAgeHuman": "1h"
},
"response": {
"totalEntries": 15,
"byTool": {"xcodebuild-build": 8, "simctl-list": 7}
}
}
`#### Configure Cache Settings
`json
{
"tool": "cache-set-config",
"arguments": {
"cacheType": "simulator",
"maxAgeMinutes": 30
}
}
`#### Clear Caches When Needed
`json
{
"tool": "cache-clear",
"arguments": {
"cacheType": "all"
}
}
`$3
#### Basic Build (Uses Smart Defaults)
`json
{
"tool": "xcodebuild-build",
"arguments": {
"projectPath": "/path/to/MyApp.xcworkspace",
"scheme": "MyApp"
}
}
`Automatically uses cached project preferences and optimal simulator selection
#### Override with Specific Configuration
`json
{
"tool": "xcodebuild-build",
"arguments": {
"projectPath": "/path/to/MyApp.xcworkspace",
"scheme": "MyApp",
"configuration": "Release",
"destination": "platform=iOS Simulator,name=iPhone 15 Pro"
}
}
`Smart Build Response:
`json
{
"buildId": "fff6ec25-b5ad-4e0f-9c47-4c71819e51bd",
"success": true,
"summary": {
"success": true,
"errorCount": 0,
"warningCount": 1,
"duration": 7075,
"scheme": "MyApp",
"configuration": "Debug",
"destination": "platform=iOS Simulator,id=ABC-123"
},
"nextSteps": [
"ā
Build completed successfully in 7075ms",
"š” Smart defaults used: optimal simulator auto-selected",
"Use 'xcodebuild-get-details' with buildId for full logs"
]
}
`$3
#### Revolutionary Progressive Disclosure - Instant Summaries
`json
{
"tool": "simctl-list",
"arguments": {
"deviceType": "iPhone"
}
}
`Progressive Response (96% Token Reduction: 57k ā 2k tokens):
`json
{
"cacheId": "sim-abc123-def456",
"summary": {
"totalDevices": 47,
"availableDevices": 31,
"bootedDevices": 1,
"deviceTypes": ["iPhone", "iPad"],
"commonRuntimes": ["iOS 18.5", "iOS 26.0"],
"lastUpdated": "2025-08-03T10:25:22.938Z"
},
"quickAccess": {
"bootedDevices": [
{
"name": "iPhone 16 - iOS 26",
"udid": "A33571BC-B564-41E8-9661-03E1356A4739",
"state": "Booted",
"runtime": "iOS 26.0"
}
],
"recentlyUsed": [...],
"recommendedForBuild": [...]
},
"nextSteps": [
"ā
Found 31 available simulators",
"Use 'simctl-get-details' with cacheId for full device list",
"Use filters: deviceType=iPhone, runtime=iOS 18.5"
],
"smartFilters": {
"suggestedFilters": "deviceType=iPhone runtime='iOS 18.5'"
}
}
`#### Progressive Detail Access - Get Full Information When Needed
`json
{
"tool": "simctl-get-details",
"arguments": {
"cacheId": "sim-abc123-def456",
"detailType": "available-only",
"deviceType": "iPhone",
"maxDevices": 10
}
}
`Full Detail Response:
`json
{
"summary": {
"totalAvailable": 23,
"showing": 10,
"bootedCount": 1
},
"devices": [
{
"name": "iPhone 16 Pro",
"udid": "ABC-123-DEF-456",
"state": "Booted",
"runtime": "iOS 26.0",
"lastUsed": "2025-08-03T10:30:00Z"
}
],
"recommendations": {
"preferredForBuild": [...],
"bootedDevices": [...]
}
}
`#### Smart Simulator Boot with Performance Tracking
`json
{
"tool": "simctl-boot",
"arguments": {
"deviceId": "ABCD1234-5678-90EF-GHIJ-KLMNOPQRSTUV"
}
}
`Boot Response with Performance Metrics:
`json
{
"success": true,
"bootTime": 4500,
"deviceId": "ABCD1234-5678-90EF-GHIJ-KLMNOPQRSTUV",
"performance": {
"avgBootTime": 4200,
"reliability": 0.95,
"recentUsage": "2024-08-03T10:30:00Z"
}
}
`$3
#### Get Detailed Build Information
`json
{
"tool": "xcodebuild-get-details",
"arguments": {
"buildId": "fff6ec25-b5ad-4e0f-9c47-4c71819e51bd",
"detailType": "warnings-only",
"maxLines": 50
}
}
`Configuration
$3
`json
{
"tool": "cache-set-config",
"arguments": {
"cacheType": "all",
"maxAgeHours": 2
}
}
`$3
- XCODE_CLI_MCP_TIMEOUT: Default timeout for operations (default: 300s)
- XCODE_CLI_MCP_LOG_LEVEL: Logging verbosity (error|warn|info|debug)
- XCODE_CLI_MCP_CACHE_DIR: Custom cache directory (default: in-memory)$3
For Claude Desktop, add to
~/Library/Application Support/Claude/claude_desktop_config.json:#### Option 1: Using NPX (Recommended)
`json
{
"mcpServers": {
"xc-mcp": {
"command": "npx",
"args": ["xc-mcp"],
"cwd": "/path/to/your/ios/project",
"env": {
"NODE_ENV": "production"
}
}
}
}
`#### Option 2: Using NPM Global Install
`json
{
"mcpServers": {
"xc-mcp": {
"command": "xc-mcp",
"cwd": "/path/to/your/ios/project",
"env": {
"NODE_ENV": "production"
}
}
}
}
`#### Option 3: Local Development Setup
`json
{
"mcpServers": {
"xc-mcp": {
"command": "node",
"args": ["/path/to/xc-mcp/dist/index.js"],
"cwd": "/path/to/your/ios/project",
"env": {
"NODE_ENV": "production"
}
}
}
}
`Note: Set the
cwd (current working directory) to your iOS project directory for proper Xcode project discovery.Intelligent Workflows
$3
1. cache-get-stats ā Check cache status and performance
2. simctl-list ā Get simulator summary (2k tokens vs 57k - instant response!)
3. simctl-get-details ā Progressive access to full simulator details when needed
4. xcodebuild-build ā Build with smart defaults (learns from success)
5. xcodebuild-get-details ā Drill down into specific build issues if needed$3
1. Quick Overview ā simctl-list returns concise summary with booted devices
2. Smart Recommendations ā Get immediate access to recently used simulators
3. Drill Down ā Use simctl-get-details with cacheId for full device lists
4. Intelligent Filtering ā Apply deviceType/runtime filters for targeted results$3
1. cache-set-config ā Customize cache timeouts for your workflow
2. Monitor build trends ā System automatically tracks performance
3. cache-clear ā Refresh when Xcode configuration changes
4. Automatic learning ā System adapts to your usage patterns$3
1. First build ā System learns project structure and preferences
2. Subsequent builds ā Automatic smart defaults based on history
3. Simulator optimization ā Boot time tracking and recommendations
4. Configuration memory ā Successful settings remembered per projectAdvanced Features
$3
- Build time trend tracking per project
- Simulator boot performance monitoring
- Cache hit rate optimization
- Configuration success rate analysis$3
- Optimal simulator suggestions based on usage patterns
- Build configuration recommendations from successful history
- Performance regression detection and alerting
- Cache optimization suggestions$3
- Project-specific preference learning
- Cross-session state persistence (planned)
- Team preference sharing (roadmap)
- Multi-workspace intelligence (roadmap)Security
- Input validation prevents path traversal attacks
- Command injection prevention through proper argument escaping
- File system permission validation
- Sandbox compatibility
- Cache isolation per project context
Development
$3
`
src/
āāā index.ts # Main MCP server entry
āāā tools/
ā āāā xcodebuild/ # Build-related tools
ā āāā simctl/ # Simulator tools
ā āāā cache/ # Cache management tools
āāā state/ # Intelligent caching system
ā āāā simulator-cache.ts # Simulator state management
ā āāā project-cache.ts # Project context awareness
āāā utils/ # Common utilities
āāā validators/ # Input validation
āāā types/ # TypeScript type definitions
`$3
`bash
npm run build # Build TypeScript
npm run dev # Development mode with watch
npm test # Run test suite
npm run lint # Code linting
npm run clean # Clean build artifacts
`Roadmap
$3
- Cross-session state persistence
- Predictive caching and pre-warming
- Advanced error prediction
- Team preference synchronization$3
- CI/CD pipeline optimization
- Performance benchmark comparisons
- Multi-project workspace awareness
- Automated optimization suggestionsContributing
1. Fork the repository
2. Create a feature branch
3. Make your changes with intelligent caching in mind
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
License
MIT License - see LICENSE file for details.
Support
For issues and questions:
- Open an issue on GitHub
- Review implementation details in the source code
- Check the progressive disclosure implementation in
src/tools/simctl/`---
XC-MCP: Where iOS development meets intelligent automation š