iOS

This MCP server lets an LLM access and manage photos on a connected iOS device from your local machine. It scans the device, indexes metadata, and provides semantic search and precise filtering so you can find, copy, and organize photos with natural language queries and exact metadata constraints.

How to use

You’ll run the MCP server locally and connect your iOS device via USB. Start by ensuring your iPhone is trusted on the computer, then use your MCP client to issue high-level actions like scanning, searching, and filtering photos.

Key workflows you can perform: scan the device to index photos, search with natural language queries (for example, find photos from a specific trip), apply exact metadata filters, and copy or rename files to your local machine for easy organization. The server caches scans so subsequent queries are fast, and you can introspect available metadata fields to fix typos or discover new fields.

How to install

Prerequisites and initial setup include macOS for iOS connectivity and Python 3.10 or newer.

Install required system tools and Python dependencies using the following steps.

# Prerequisites
# macOS-specific tools
brew install libimobiledevice ifuse exiftool

# Python
# Use your preferred Python 3.10+ installation method
# Create and activate a virtual environment if desired
python3.10 -m venv venv
source venv/bin/activate

# Install project dependencies
pip install -r requirements.txt

# Ensure you are on macOS and have the necessary USB permissions for iOS access

Additional setup and usage notes

Connect your iPhone via USB and ensure you have trusted the computer on the device. You can then start the MCP server using the built-in command shown in the usage section.

Run the MCP server directly with the provided command.

Configure MCP clients to point at this server so you can issue scan, search, and file management commands.

Configuration and MCP server endpoints

The server is started locally using the MCP command line. Use the following command to launch the server from your project root.

mcp run src/server.py

Client configuration examples

Claude Desktop clients can reference the local MCP server by adding a server entry that points to the local Python server script.

{
  "mcpServers": {
    "ios_mcp": {
      "command": "python",
      "args": ["/absolute/path/to/ios_mcp/src/server.py"]
    }
  }
}

Security and access considerations

Only connect to MCP servers you control on trusted networks. When possible, limit device access to authorized machines and keep the server updated with the latest dependencies to minimize potential security risks.

Troubleshooting tips

If the server fails to start, verify Python 3.10+ is active, USB permissions are correct, and the path to the server script is accurate. Check that the device is trusted and that the required system tools are installed.

Notes

This MCP server exposes tools to list connected devices, scan and cache photos, perform semantic searches, apply exact filters, and manage file copies with optional renaming based on metadata. It also supports introspection to discover available metadata fields and correct typos.

Available tools

list_connected_devices

Lists UDIDs of connected iOS devices.

scan_and_cache_photos

Mounts the device, scans DCIM, and indexes metadata into the Vector DB.

search_files

Semantic search using natural language for photos based on photo metadata.

filter_files

Exact metadata filtering with specified key-value pairs.

count_files

Counts files matching semantic or exact criteria.

group_files

Groups files by a field and returns counts.

run_advanced_query

Performs complex queries with sorting, pagination, and projection.

run_aggregation_pipeline

Processes data through a multi-stage pipeline (MongoDB style).

get_metadata_keys

Lists all available metadata fields.

find_similar_metadata_keys

Finds valid keys similar to a potentially misspelled key.

read_image

Reads and resizes an image, returning base64 data.

copy_files_to_local

Copies files to a local directory with optional renaming.

mount_device_for_file_access

Manually mount the device for operations outside the standard flow.

check_db_status

Checks the health of the database connection.