# Claude Code Setup Guide
This guide walks you through setting up the iOS Development MCP Server with Claude Code.
## Prerequisites
- **macOS** (iOS Simulator only available on macOS)
- **Xcode** 15+ with Command Line Tools installed
- **Node.js** 18+
- **Claude Code** CLI installed
## Quick Install (Recommended)
Run the automated installation script:
```bash
cd /Users/d/Documents/projects/ios-dev-mcp-server
./install-claude-code.sh
```
This script will:
1. Check prerequisites (macOS, Node.js, Xcode)
2. Build the project if needed
3. Configure Claude Code settings automatically
4. Provide next steps
## Manual Installation
If you prefer to configure manually:
### 1. Build the Project
```bash
cd /Users/d/Documents/projects/ios-dev-mcp-server
npm install
npm run build
```
### 2. Configure Claude Code
#### Option A: Using `claude mcp add` (if available)
```bash
claude mcp add ios-dev \
--command node \
--args "/Users/d/Documents/projects/ios-dev-mcp-server/build/index.js"
```
#### Option B: Manual Configuration
Edit your Claude Code settings file:
**Location:** `~/.config/claude-code/settings.json`
Add the following to the `mcpServers` section:
```json
{
"mcpServers": {
"ios-dev": {
"command": "node",
"args": [
"/Users/d/Documents/projects/ios-dev-mcp-server/build/index.js"
],
"metadata": {
"name": "iOS Development MCP Server",
"description": "Comprehensive iOS simulator control and Swift/Xcode development tools",
"version": "0.1.0"
}
}
}
}
```
**Note:** Replace the path with your actual installation path if different.
### 3. Restart Claude Code
After configuration, restart Claude Code to load the new MCP server:
```bash
# If Claude Code is running
pkill -f "claude-code" || true
# Start Claude Code
claude
```
## Verification
Test that the MCP server is working:
```bash
# In Claude Code, try these prompts:
```
**Example prompts:**
- "List all available iOS simulators"
- "Boot an iPhone 15 Pro simulator"
- "Get info about the booted simulator"
- "Shut down the simulator"
## Available Tools
### Current (v0.1.0)
ā
**Simulator Device Management (4 tools)**
- `simulator_list_devices` - List all iOS simulators
- `simulator_boot` - Boot a simulator
- `simulator_shutdown` - Shutdown a simulator
- `simulator_get_info` - Get device details
### Coming Soon
š§ **Simulator UI (4 tools)**
- Screenshot capture with compression
- Tap, swipe, long press gestures
š **Full Feature Set (37+ tools planned)**
- App lifecycle management
- Build and test automation
- Xcode project management
- Swift Package Manager integration
## Troubleshooting
### MCP Server Not Loading
1. **Check build:**
```bash
cd /Users/d/Documents/projects/ios-dev-mcp-server
npm run build
```
2. **Verify settings file:**
```bash
cat ~/.config/claude-code/settings.json
```
3. **Check permissions:**
```bash
chmod +x /Users/d/Documents/projects/ios-dev-mcp-server/build/index.js
```
### "No booted device" Error
Boot a simulator first:
```bash
# From Claude Code:
"Boot an iPhone 15 Pro simulator"
# Or manually:
open -a Simulator
```
### "Command not found: xcrun"
Install Xcode Command Line Tools:
```bash
xcode-select --install
```
### Platform Error
This server requires macOS. Ensure you're running on macOS, not Linux or Windows.
## Configuration Options
### Custom Build Path
If you move the project or use a custom build path, update the `args` in your settings:
```json
{
"mcpServers": {
"ios-dev": {
"command": "node",
"args": ["/path/to/your/ios-dev-mcp-server/build/index.js"]
}
}
}
```
### Multiple Servers
You can run multiple MCP servers simultaneously:
```json
{
"mcpServers": {
"ios-dev": {
"command": "node",
"args": ["/path/to/ios-dev-mcp-server/build/index.js"]
},
"another-server": {
"command": "node",
"args": ["/path/to/another-server/index.js"]
}
}
}
```
## Development Mode
For active development with automatic rebuilds:
### Terminal 1 - Watch Mode
```bash
cd /Users/d/Documents/projects/ios-dev-mcp-server
npm run dev
```
### Terminal 2 - Claude Code
```bash
claude
```
When you make changes to the source code, the watch mode will automatically rebuild. Restart Claude Code to pick up changes.
## Using with MCP Inspector
For testing without Claude Code:
```bash
cd /Users/d/Documents/projects/ios-dev-mcp-server
npm run inspector
```
Opens a web UI at http://localhost:6274 for interactive testing.
## Next Steps
- **Explore tools:** Try the 4 available simulator management tools
- **Check updates:** Run `git pull` periodically for new features
- **Report issues:** Open an issue on GitHub if you encounter problems
- **Contribute:** See CONTRIBUTING.md (if available)
## Support
For issues or questions:
1. Check the main [README.md](./README.md)
2. Review error messages carefully
3. Ensure all prerequisites are met
4. Check Claude Code logs for detailed error information
## Uninstalling
To remove the iOS Dev MCP Server from Claude Code:
### Option 1: Manual
Edit `~/.config/claude-code/settings.json` and remove the `"ios-dev"` section from `mcpServers`.
### Option 2: CLI (if available)
```bash
claude mcp remove ios-dev
```
Then restart Claude Code.
---
**Version:** 0.1.0
**Last Updated:** January 2026
**Platform:** macOS only
