-
securityA
license-
qualityThis MCP server allows you to connect MCP clients with Toolhouse's tools.
XC-MCP is an intelligent Xcode CLI wrapper that optimizes developer workflows through progressive disclosure, smart caching, and AI-driven learning to address MCP client token limits.
Core Capabilities:
Xcode Project Management: Execute builds with smart defaults, list targets/schemes/configurations, show SDKs, get version info, and clean artifacts with cached logs and learning systems
Simulator Control: Manage iOS simulators with concise summaries, progressive disclosure for full details, boot/shutdown operations with performance tracking, and smart recommendations
Intelligent Caching System: Multi-layer caching with configurable timeouts, comprehensive statistics, cache clearing, and cached response listing
Data Persistence: File-based state persistence across server restarts for cache data and learned patterns
AI-Driven Optimization: Learning from usage patterns, performance metrics tracking (build/boot times), and adaptive intelligence for improved recommendations and workflow efficiency
Provides intelligent Xcode CLI tooling with progressive disclosure, enabling build operations, simulator management, project discovery, and cache management while solving token overflow issues through smart caching and concise summaries
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.
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)xcodebuildlogs: 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 |
| List targets, schemes, configurations | ✓ |
| Available SDKs | - | |
| Xcode version info | - | |
Build Operations |
| Build with smart defaults | ✓ (via buildId) |
| Clean build artifacts | - | |
| Access cached build logs | - | |
Simulator Management |
| Simulator list with 96% token reduction | ✓ (via cacheId) |
| Progressive access to full simulator data | - | |
| Boot with performance tracking | - | |
| Graceful shutdown | - | |
Cache Management |
| Cache performance metrics | - |
| Configure cache timeouts | - | |
| Clear cached data | - | |
| 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 verbosityXCODE_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.
local-only server
The server can only run on the client's local machine because it depends on local resources.
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
- AsecurityAlicenseAqualityA MCP server that enables LLMs to interact with iOS simulators through natural language commands.Last updated -247Apache 2.0
- AsecurityAlicenseAqualityMCP 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 -2423243Apache 2.0
- -securityFlicense-qualityAn 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 -5