Xcode MCP Server Tools Overview

This document provides a comprehensive overview of the tools available in the Xcode MCP Server and explains how they interact with Xcode projects.

Server Architecture

The Xcode MCP Server is organized into the following modules:

• Project Management: Tools for working with Xcode projects
• File Operations: Tools for reading and writing files
• Build & Testing: Tools for building and testing projects
• CocoaPods Integration: Tools for managing CocoaPods dependencies
• Swift Package Manager: Tools for managing Swift Package Manager functionality
• Simulator Tools: Tools for interacting with iOS simulators
• Xcode Utilities: Miscellaneous Xcode-specific tools
• Path Management: System for secure file access and directory navigation

Project Management Tools

Tool	Description
set_projects_base_dir	Sets the base directory where Xcode projects are stored
set_project_path	Sets the active Xcode project (xcodeproj, xcworkspace, or SPM); can optionally open the project in Xcode
get_active_project	Retrieves detailed information about the active project
find_projects	Finds Xcode projects in the specified directory
get_project_configuration	Retrieves configuration details for the active project
detect_active_project	Detects the active Xcode project with option to respect existing project settings
change_directory	Changes the active directory for relative path operations
push_directory	Pushes current directory to stack and changes to a new directory
pop_directory	Returns to previous directory from stack
get_current_directory	Shows the current active directory

These tools help you navigate and manage Xcode projects. The server supports multiple project types including regular .xcodeproj files, workspaces (.xcworkspace), and Swift Package Manager projects (Package.swift).

Key Tool Parameters

set_project_path

• projectPath: Path to the .xcodeproj, .xcworkspace, or directory with Package.swift
• setActiveDirectory: If true (default), sets the active directory to the project directory
• openInXcode: If true, opens the project in Xcode automatically, ensuring alignment between the server and Xcode

detect_active_project

• forceRedetect: If true, forces rediscovery of open projects in Xcode, otherwise respects existing project settings (default: false)

File Operation Tools

Tool	Description
read_file	Reads the contents of a file within allowed directories
write_file	Writes or updates file content within allowed directories
copy_file	Copies a file or directory to a new location
move_file	Moves a file or directory to a new location
delete_file	Deletes a file or directory
create_directory	Creates a new directory
list_project_files	Lists all files within an Xcode project
list_directory	Lists directory contents with options for format and hidden files
get_file_info	Gets detailed information about a file or directory
find_files	Searches for files matching a pattern in a directory
resolve_path	Shows how a path would be resolved
check_file_exists	Checks if a file or directory exists

File operation tools allow you to interact with files securely. All operations use the path management system for validation and security.

Build & Testing Tools

Tool	Description
analyze_file	Analyzes a source file for potential issues using Xcode's static analyzer
build_project	Builds the active Xcode project with specified configuration and scheme
run_tests	Executes tests for the active Xcode project, optionally with a test plan

Build and testing tools interact with Xcode's build system to compile your projects and run tests. They use xcodebuild in the background.

CocoaPods Integration

Tool	Description
pod_install	Runs 'pod install' in the active project directory
pod_update	Runs 'pod update' in the active project directory
pod_outdated	Checks for outdated dependencies in the project
pod_repo_update	Updates the local CocoaPods spec repositories
pod_deintegrate	Removes CocoaPods from the project
pod_init	Initializes a new Podfile in the project
check_cocoapods	Checks if the active project uses CocoaPods and returns setup information

CocoaPods tools allow you to manage CocoaPods dependencies in your iOS projects. These tools require CocoaPods to be installed on your system.

Swift Package Manager Tools

Tool	Description
init_swift_package	Initializes a new Swift Package Manager project with options for type and testing
add_swift_package	Adds a Swift Package dependency to the active project
update_swift_package	Updates dependencies with options for specific packages and versions
swift_package_command	Executes arbitrary Swift Package Manager commands
build_swift_package	Builds a Swift Package with configuration options
test_swift_package	Tests a Swift Package with filtering and parallel options
show_swift_dependencies	Displays dependency graphs in various formats
clean_swift_package	Cleans build artifacts with options for global cache
dump_swift_package	Dumps the Package.swift manifest as JSON

Swift Package Manager tools provide comprehensive support for Swift packages and dependencies. They interact with the Swift Package Manager CLI and provide enhanced error reporting.

Simulator Tools

Tool	Description
list_simulators	Lists all available iOS simulators
boot_simulator	Boots an iOS simulator identified by its UDID
shutdown_simulator	Shuts down an active iOS simulator
install_app	Installs an app on a simulator
uninstall_app	Removes an app from a simulator
launch_app	Launches an app on a simulator
terminate_app	Terminates a running app on a simulator
take_screenshot	Captures a screenshot of a simulator
record_video	Records video of simulator activity

Simulator tools allow you to interact with iOS simulators. They use the simctl command-line tool that is part of Xcode.

Xcode Utilities

Tool	Description
run_xcrun	Executes a specified Xcode tool via 'xcrun'

See docs/exec-safety-audit.md for a review of shell command usage.