jontolof/xcode-build-mcp
If you are the rightful owner of xcode-build-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Xcode Build Server MCP is a highly optimized server designed to streamline Xcode operations, significantly reducing token usage while maintaining full functionality for iOS/macOS development workflows.
Xcode Build Server MCP
A highly optimized Model Context Protocol (MCP) server for Xcode operations that reduces token usage by 83% while maintaining full functionality for iOS/macOS development workflows.
๐ฏ Key Features
- 83% Token Reduction: From ~47,000 to ~8,000 tokens (14 tools vs 83)
- 90%+ Output Filtering: Intelligent filtering of verbose xcodebuild output
- Smart Auto-Detection: Automatically detects project types and selects appropriate simulators
- Unified Interface: Single tools for multiple scenarios instead of variant proliferation
- Zero Dependencies: Built with Go standard library for maximum reliability
- Real-time Streaming: Progressive output for long-running operations
- Intelligent Caching: LRU cache for frequently accessed project data
๐ Why This Project?
Popular xcode-build MCP implementation suffers from severe tool proliferation:
- 83 redundant tools consuming ~47,000 tokens
- Separate tools for project vs workspace (2x duplication)
- Separate tools for simulator name vs ID (2x duplication)
- Separate tools for each platform (4x multiplication)
- Most developers use <10% of available tools
Our solution consolidates everything into 14 essential tools that cover 100% of common workflows.
๐ Quick Start
Prerequisites
- Go 1.21 or higher
- Xcode 14.0 or higher
- macOS 12.0 or higher
Installation
# Clone the repository
git clone https://github.com/jontolof/xcode-build-mcp.git
cd xcode-build-mcp
# Build the server
go build -o xcode-build-mcp cmd/server/main.go
# Install to PATH (optional)
sudo cp xcode-build-mcp /usr/local/bin/
Basic Usage
# Run the MCP server
xcode-build-mcp
# Run with debug logging
MCP_LOG_LEVEL=debug xcode-build-mcp
# Run with custom output filtering
MCP_OUTPUT_MODE=minimal xcode-build-mcp
Integration with MCP Clients
Add to your MCP client configuration:
{
"mcpServers": {
"xcode-build": {
"command": "xcode-build-mcp",
"args": ["stdio"],
"env": {
"MCP_LOG_LEVEL": "info",
"MCP_OUTPUT_MODE": "standard"
}
}
}
}
๐ ๏ธ The 14 Essential Tools
Build & Test Tools
1. xcode_build
Universal build command that auto-detects project type and simulator.
{
"tool": "xcode_build",
"parameters": {
"path": "MyApp.xcodeproj",
"scheme": "MyApp",
"configuration": "Debug"
}
}
2. xcode_test
Universal test execution with parsed results.
{
"tool": "xcode_test",
"parameters": {
"path": "MyApp.xcodeproj",
"scheme": "MyAppTests",
"filter": "testLogin*"
}
}
3. xcode_clean
Clean build artifacts and derived data.
{
"tool": "xcode_clean",
"parameters": {
"path": "MyApp.xcodeproj",
"derivedData": true
}
}
Discovery Tools
4. discover_projects
Find all Xcode projects in directory tree.
{
"tool": "discover_projects",
"parameters": {
"root": ".",
"maxDepth": 3
}
}
5. list_schemes
List available build schemes.
{
"tool": "list_schemes",
"parameters": {
"path": "MyApp.xcodeproj"
}
}
6. list_simulators
List available iOS/macOS simulators.
{
"tool": "list_simulators",
"parameters": {
"platform": "iOS",
"available": true
}
}
Runtime Tools
7. simulator_control
Boot, shutdown, or reset simulators.
{
"tool": "simulator_control",
"parameters": {
"action": "boot",
"identifier": "iPhone 15 Pro"
}
}
8. install_app
Install apps to simulators or devices.
{
"tool": "install_app",
"parameters": {
"appPath": "build/MyApp.app",
"destination": "iPhone 15 Pro"
}
}
9. launch_app
Launch installed apps with optional arguments.
{
"tool": "launch_app",
"parameters": {
"bundleId": "com.example.myapp",
"destination": "iPhone 15 Pro",
"arguments": ["--debug", "--mock-data"]
}
}
Debug Tools
10. capture_logs
Capture and filter device/simulator logs.
{
"tool": "capture_logs",
"parameters": {
"action": "start",
"destination": "iPhone 15 Pro",
"filter": "MyApp"
}
}
11. screenshot
Capture simulator screenshots.
{
"tool": "screenshot",
"parameters": {
"destination": "iPhone 15 Pro",
"outputPath": "screenshots/login.png"
}
}
12. describe_ui
Get UI element hierarchy for testing.
{
"tool": "describe_ui",
"parameters": {
"destination": "iPhone 15 Pro",
"format": "tree"
}
}
Automation Tools
13. ui_interact
Perform UI interactions (tap, swipe, type).
{
"tool": "ui_interact",
"parameters": {
"destination": "iPhone 15 Pro",
"action": "tap",
"parameters": {
"x": 100,
"y": 200
}
}
}
14. get_app_info
Extract app metadata and information.
{
"tool": "get_app_info",
"parameters": {
"appPath": "build/MyApp.app",
"info": "all"
}
}
๐ Performance
Token Usage Comparison
Metric | Current Implementation | Our Implementation | Improvement |
---|---|---|---|
Tool Count | 83 tools | 14 tools | 83% reduction |
Token Usage | ~47,000 | ~8,000 | 83% reduction |
Output Verbosity | 100% | <10% | 90%+ filtering |
Response Time | Variable | <100ms (cached) | Consistent |
Output Filtering Example
Before (Raw xcodebuild output):
CompileSwift normal x86_64 /Users/dev/MyApp/Sources/ViewControllers/LoginViewController.swift (in target 'MyApp' from project 'MyApp')
cd /Users/dev/MyApp
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift -frontend -c -primary-file...
[500+ more lines of compilation details]
After (Filtered output):
Building MyApp (Debug)...
โ Compiled LoginViewController.swift
โ Compiled AppDelegate.swift
โ Linking MyApp.app
Build succeeded in 12.3s
Output: build/Debug-iphonesimulator/MyApp.app
๐ง Configuration
Environment Variables
Variable | Default | Description |
---|---|---|
MCP_LOG_LEVEL | info | Logging level: debug , info , warn , error |
MCP_OUTPUT_MODE | standard | Output verbosity: minimal , standard , verbose |
MCP_CACHE_TTL | 300 | Cache TTL in seconds |
MCP_TIMEOUT | 300 | Command timeout in seconds |
XCODE_PATH | Auto-detect | Path to Xcode.app |
Configuration File
Create ~/.xcode-build-mcp/config.json
:
{
"outputMode": "standard",
"caching": {
"enabled": true,
"ttl": 300
},
"filtering": {
"rules": "default",
"customPatterns": []
}
}
๐งช Development
Building from Source
# Clone repository
git clone https://github.com/[username]/xcode-build-mcp.git
cd xcode-build-mcp
# Install dependencies (minimal)
go mod download
# Build
go build -o xcode-build-mcp cmd/server/main.go
# Run tests
go test ./...
# Run with race detection
go test -race ./...
# Generate coverage report
go test -cover ./...
Project Structure
xcode-build-mcp/
โโโ cmd/server/ # Server entry point
โโโ internal/
โ โโโ mcp/ # MCP protocol implementation
โ โโโ xcode/ # Xcode integration
โ โโโ filter/ # Output filtering
โ โโโ cache/ # Caching system
โ โโโ tools/ # Tool implementations
โโโ pkg/types/ # Shared types
โโโ tests/ # Test suites
โโโ docs/ # Documentation
Testing
# Run all tests
make test
# Run integration tests
make test-integration
# Run benchmarks
make bench
# Check coverage
make coverage
๐ Documentation
- - Detailed design rationale
- - Implementation roadmap and milestones
- - Complete tool API documentation
๐ Benchmarks
# Token usage benchmark
Original implementation: 46,950 tokens
Optimized implementation: 7,910 tokens
Reduction: 83.15%
# Output filtering benchmark
Input: 10,000 lines of xcodebuild output
Filtered output: 847 lines
Reduction: 91.53%
Processing time: 8.2ms
# Response time (cached operations)
discover_projects: 12ms
list_schemes: 8ms
list_simulators: 23ms
xcode_build (cached): 94ms
๐ Security
- No sensitive data is logged or cached
- All user paths are validated
- Command injection protection
- Secure handling of build artifacts
๐ License
This project is licensed under the MIT License - see the file for details.
๐ Acknowledgments
- Inspired by the need for efficient MCP servers
- Built for the iOS/macOS development community
- Optimized for AI-assisted development workflows
๐ Support
- GitHub Issues - Bug reports and feature requests
- Discussions - General discussions
- Wiki - Additional documentation
๐ฆ Project Status
Current Phase: Production Ready โ
- Design specification
- Implementation plan
- Core MCP server
- Tool implementation (14 essential tools)
- Testing & optimization
- Output filtering (90%+ reduction)
- Production release
Built with โค๏ธ for the iOS/macOS development community